Hacker News Reader

Comment by adrianN | Hacker News Reader

A sufficiently detailed design document is essentially indistinguishable from code. How do you avoid the problems you encounter when writing code while writing the design document?

View on HN

In my experience it is not one or the other. You can experiment first and then document, or vice versa. The point of documentation is "writing is thinking". The act of writing forces you to think through your ideas in ways that other modes of thinking do not. This is especially important when you are working on a team and need to share your ideas.

I agree that sufficiently detailed design documents are indispensable from code and should be avoided. However, clearly documenting the why, what and how of your work helps align everyone clearly. It also helps an individual clarify their ideas to themselves. It is hard to write clearly & succinctly. It takes time & practice, but I find it essential.

You know your programming language very very well, AND design for failure. What I do normally is first write the API of the library I want to use. Then I might start detailing things, which becomes some early documentation/API. Finally I try to implement it in code, and if I find a truly blocking code bit I restructure my assumptions about what is possible with my API and go back to the API/docs.

For example, at some point I knew I wanted to set localStorage and cookies values just like this:

    cookie.token = '1234';
    local.token = '1234';

I know enough Javascript, and the language is flexible enough, that I know that I could achieve that, either with getter/setters or with the more flexible Proxy(). So I continued writing the other methods first; how would it look ideally to "read" a value? To "delete" a value? Etc:

    console.log(cookie.token);
    delete cookie.token;
    // ...

I wrote few examples of each, put it all in some documentation, and then wrote some tests, following those documentation examples:

    expect(cookie.token).toBe(null);
    cookie.token = '1234';
    expect(cookie.token).toBe('1234');

And finally wrote the code for it. Later I wanted to add IndexedDB, BUT! That is async! My abstraction was broken, or was it? I could just modify a single method and everything else would work as expected:

    db.token = '1234';
    console.log(await db.token);  // <= added await here
    delete db.token;

I have the same reaction to this as I would to "a sufficiently detailed blueprint is essentially indistinguishable from a building". I'd be very interested to see a software design document so opinionated and prescriptive about implementation that it leaves no room for a software engineer to add value.

I think it was an extreme example but we didn't. The design phase is exactly when you should be formulating ideas and throwing away things that don't work. The theory is that this is easier to do before code is laid down. They were way too granular though so it was super painful even in design phase to get these design docs together.

I think the design phase in this instance required far too much detail. Some middle ground would probably be best imo.

You can’t necessarily, unless you write it at a higher level of abstraction* and trust the engineers are correct when they say it’s feasible to implement in a reasonable amount of time. Now your team is aligned and coordinated, even if the team consists of one person.

* Shape Up - https://basecamp.com/shapeup

> A sufficiently detailed design document is essentially indistinguishable from code.

Stealing this one. What a great quote!

Reply on news.ycombinator.com