Plan first, then code

Dear new developer,

I thought this article was worth sharing, as it is a relatively inexperienced developer talking to newer devs. But as I read it, one piece of advice stuck out and is worth emphasizing.

Plan first, then code

Roberto Hernandez

This is fundamental. Unlike, say carpentry, where planning is critical because you waste material if you don’t, coding sometimes feels like you can “just start.” After all, if you make a mistake, you can delete the code and start over (as long as you’re operating on your own development environment, not production). Seeing what you’re building is satisfying, both to you as a builder and anyone else you share your work with.

However, “just starting” is a recipe for waste, if what you start is writing code.

The first thing you should do before writing a single line of code is understand the problem. Depending on the size and scale of the problem, confirming this understanding could be as simple as repeating the request back to the person ho made it: “so what you are saying is you want me to change the button text to blue” and thinking through the ramifications: “that will work on form A and B, but what about form C?”.

Or it could be as complicated as writing up a specifications document with the proposed changes and architecture, getting feedback on it, running it by the appropriate people or committees, and getting sign-off from stakeholders, including executives and customers.

Then, after you confirm you understand the problem and proposed solution, plan on how you are going to execute against it. For a small problem, this could involve starting immediately by writing or thinking of a list of tasks to do, though often you’ll want to add it to a todo list or calendar to ensure this task isn’t lost among the sea of other tasks you have. For a larger problem, there may be cross team coordination required, so: meetings and documents.

After you understand the problem and have a plan for how to accomplish this goal, you can begin writing code.

Avoid jumping in and writing code because the time to feedback is long. Compared to what? Compared to text, images or meetings. These are so much easier to iterate. If you write some code to solve the wrong problem or address it in the wrong manner, you’ve used more time than you would have if you’d talked through the problem.

It is also harder to communicate concepts with code, especially with non technical colleagues. Even with fellow engineers, a diagram or conversation is an easier way to explain ideas than written code. I’ve often whiteboarded a solution in a fraction of the time it would have taken to prototype it. Code is more precise and you can’t handwave a problem away, but there’s lots of chaff around the germ of the idea in many code bases.

There are times when writing code is the right way to start, though. This is called prototyping and if there’s no way to gain an understanding of the problem by reading, learning, discussing or otherwise approaching it, write some code to explore it. However, be prepared to throw this code away, as it will be the equivalent of a hastily scratched note on a napkin.

I do want to emphasize that this understanding and planning process doesn’t always have to be heavyweight and formal. In fact, for smaller tasks, you may internalize this process and not even realize you are doing it.

Next time you are working on a small task, take a moment and think about how you break it up into even smaller bits of work: “ok, I need to add this form. Therefore I need a model and a view too, and what are the methods I should add to validate the input?”

You don’t need to produce documentation and artifacts for every decision, but you would do well to at least in your own head think through the tasks and the ramifications of those tasks. This will help you look around corners and see issues that may arise because of your solution. If you do, you can modify the solution, again, before any code is written.

Sincerely,

Dan