Hacker News Reader

Comment by 2OEH8eoCRo0 | Hacker News Reader

How long have you been a software engineer?

I've found that going straight into hacking on something can end up biting me in the ass for big projects. I've also worked where we would do everything up front in a design document all the way down to functions, what args they take, and pseudocode for everything. The code would then take a day or two with nothing to redo.

View on HN

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?

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

Stealing this one. What a great quote!

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.

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

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 don't think it's about experience. It's just different approaches geared to the individual. I really dislike it when people assume that anything other than their way of working is down to experience.

I've been doing this for 10 years and I've tried the design doc first route and it's arduous for me. I have coworkers who absolutely love that route.

I generally just do it in parallel. Coding to me is like sketching. So I get down my ideas in code, and I document the design as I go. I switch between the two as each one informs the other.

Not the guy you asked, but personally I've been one long enough to know that iterative design/implementation often produces a better design than waterfall. In waterfall, you have to think of everything at the beginning, and you aren't smart enough. Nobody is.

In iterative, sure, you have a design (often informal and sketchy), and you try implementing it, and as you do you find out why certain aspects were a bad idea, and you change the design to fix those, and you find more things that were bad ideas, and you fix those, and so on. By the time you're done, you have either a nice clean design or a total pile of garbage, depending on whether you did real redesigns or just kludged some bandaids on.

Writing the documentation up front doesn't prevent iteration. But it means that you're going to have to re-write it every time you change the design. And it means that you're going to have to flesh out the initial design enough to write the documentation for it. This is somewhat wasteful.

I agree. I'm not condoning waterfall though. I only mean that planning has value.

I've had this bite me in the ass on many projects too, but I still agree with the parent. When I get an idea I get a rush of motivation to implement it. If, after that rush is over, all I have is a document, the motivation isn't coming back and the project isn't getting finished. Starting with a mostly-functional MVP means I can show it to people or use it myself, which gives me the extra motivation needed to make it less hacky/more maintainable/perform better/all the other things, that I could've thought about in the planning phase.

(I just went through this cycle in the last month or so actually - I got pissed off at the state of public transport apps after I missed a train, so I decided I should make my own. I made a buggy hacked-together web app, started using it daily and showing it to people. Every time I used it, it made me want to work on it more, so I did - rewrote the backend to cache and segment data properly, made the map run at a non-sideshow framerate, made the icons consistent, started building a native version... It's actually getting close to something I'd call "good" now. Knowing myself, this would never have happened had I started off with a specification or even a mockup)

What kind of systems do you develop and what stack do you use?

Software developers tend to impose their habits on everyone thinking the circumstances do not matter. But well, they do. A lot.

Both the article, you, and the GP are doing this. I've just read the first few comments, but I expect to find a lot more of it there.

Anyway, if the strictness isn't imposed by the problems you are solving, you may gain from pushing it into your tools and getting some experience with less strict procedures too. Just like the GP may gain from trying some more strict procedures for a while.

What exactly am I doing? I'm saying that I've experienced both extremes but I am not endorsing either of them. What works best obviously depends on circumstances.

Reply on news.ycombinator.com