A key part of any development that I do is create some form of a design. For anyone who has gone through programming classes in school, the design process is fairly limited. Most of the time, students will go right to the code. That has not been my experience in the real world.
I generally go through an entire process when I’m about to start developing something. I may even start doing this months in advance depending on the scope.
Speaking of scope, I’m going to limit my scope for what I think a design is by starting with what I think they are not. A design is not a detailed account of the implementation of your solution. It should not be filled with code unless it’s an API that will be used by others (still a little iffy though).
To me, a design is a high level overview of what your plan is. It contains information on what the problem is, maybe some mock ups, and what your solution to the problem is at a high level. I generally do these things in that order, and there’s a reason why.
Identify the problems
You need to have a full understanding of the problem that you plan to fix. An understanding of the problem guides the rest of the process. It means you understand the workflow and what users are experiencing. Once you determine the high level problem you can figure out what how it should actually behave.
From there, you can go a little low-level and determine where in the code the problem appears and what state causes the issue. Once you narrow down to where it lives in the code, you can analyze the code path that you take to get there. Here’s where the code can trick you.
At the low-level, the problem may not be where it appears on the surface. It could be a bug anywhere along the code path that could lead to the issue. A caller could be sending the wrong data to the function or something like that. This is really the point where you figure out the true root cause. After you have a full understanding, you move onto the next step.
Describe the desired behavior
Using the information you gathered in the problem identification phase, you can most likely determine what the behavior should be. Here’s where you can describe what things should look like from the user perspective. This is a really good place to include mockups. There’s still not a whole ton in detail of the fix here.
Describe your solution
This is a high level overview of how you are going to fix your problem. This will be an area to write some pseudo code for your logic. You can also put some API information here if that’s the design’s purpose. Mainly you are answering the “how” here.
Answering the whys
Now that you’ve answered the “how” you will also need to explain the “why”. In my opinion, the why is the more important thing to answer (assuming you write decent code). The why gives a snapshot of the reasons you made your design decisions that you did at this time. You will most likely not understand the why just from reading code.
Some whys:
- Why use that data structure?
- Why update that file?
- Why this specific UI change? (Always contentious)
- Why is this the right fix?
It may seem obvious, but designs put down in concrete words what you are doing. It makes things less ambiguous. Someone could look at your code, and add something that you left out for a specific reason. If you document that reason, it’s more likely that someone will avoid the pitfall.
Some final thoughts
Ultimately, a design is a way of documenting the decisions that you have made. You are backing up your decisions with research, fact, and data. The other thing to realize is that your decisions will have consequences, and your design should outline some of those as well. It’s why the why is so important. If you have reasoning for your decisions and others that agree with you, it is helpful. Your decisions will inevitably upset someone, but a design helps you understand what you are doing and why. It gives support and weight to your decisions, and may answer soneone’s questions before they come looking for you.
One last thing on designs. Be mindful of the use of words like “just”. The link is a blog post from another developer, but it’s really worth the read. Using words like just gloss over some important details. Often those details are going to get you in the most trouble. Words like just should always prompt further questioning. In my experience, a lot of scope-creep lives in that word.