Ask HN: What do you do before you start writing code?

[mpblampo]

I'm a relatively junior engineer, but recently I've been working on a more complex project than I'm used to.

On a couple of recent occasions, I've written a bunch of code, only to have my colleagues correctly point out some decisions I'd made in writing it that made the code more complicated, and harder to reason about, than necessary (e.g. which logic should belong in which function, or what data structure I should use for something). I'm sure that this has amounted to a lot of wasted time. If I could have foreseen these decisions before writing code, or even just realized while writing code that I was making decisions that I ought to stop and think about, I wouldn't have made these more complicating choices, and wouldn't have had to spend all this time reworking my code.

(Of course, if I can learn a good lesson from this, the time will not have been wasted. Hence this post.)

The thing is: We'd spent significant time planning the structure of this project, with (I'd thought) clear documents and diagrams explaining what components we needed and how they would interact. When I started coding, I felt pretty well prepared, and confident that the thing would basically write itself.

So, HN: What steps do you take before setting out to write code? Are there principles that you use to decide that your plan/design is sufficiently detailed?

And, assuming there will be cases when the plan does not anticipate all design decisions: When you're coding, how do you avoid making decisions that will waste a lot of your time?

[Smudge]

Firstly, time spent learning is not time wasted!

Secondly, the best way to avoid making painful design decisions is... to make them enough times that you instinctively remember them. There aren't many shortcuts to developing that instinct, so take this opportunity to try and generalize your learnings -- what do you recognize now that you didn't see when you started the project? A healthy amount of retrospection will make you a better engineer, and you'll also get better at identifying uncertainties and risks before you start coding.

Lastly, up-front planning and design documents can only get you so far. They're important, sure, but at some point you'll be down in the nitty gritty details, and you'll need to make unanticipated course corrections. As you gain experience you'll start being able to fill in more of those gaps on your own, but until then, you'll want to loop in other engineers more frequently.

One of the qualities of a senior engineer is that they act as a force multiplier for their team. So as a relatively junior engineer, don't be afraid to make use of your senior engineers! They should be there to support you and make you better, beyond just helping you plan out a project. If possible, pair on some of the trickier parts with them, so that you can see how they'd approach the problem and start picking up on things that might not seem so obvious to you right now.

Hope that helps!

[itamarst]

Over time these small wastes-of-time will decline, as you get more experienced and learn from feedback. But there's also the really big wastes of time: working on wrong thing, and building something with assumption that turns out to be false. The latter has been a problem for me recently, so been working on it by adding step 4 below.

Here's vague model of what I do:

1. Figure out what's really important to achieve: ask why you're doing something, what the constraints are. Figure out if you really have best solution, maybe there's different way to solve real problem.

2. Sketch out a design, in my head or in writing depending on complexity.

3. Figure out riskiest assumptions.

4. Try to build smallest possible end-to-end proof-of-concept implementation. This will validate or invalidate assumptions, and usually influence design in some way.

5. Start on real coding.

(If you'd like to learn from mistakes I've made over the years, in design and testing and writing software, I write a weekly email with a mistake and what I learnt from it: https://softwareclown.com)

[wdiamond]

there are no such thing of waste of time, except when you delete code. if you have a basic design that code can be used for prototypes. if you have a complex design that code will take your time to handle complex. but if you can't handle all the code you ever write, so the problem is not the code, then you might organize your global assets in a way you can remember how they are organized. but if you are talking about achieving faster your goals then you don't need to code you need lots of people coding and people that can manage a developer team.