An effective tool for building a new feature similar to the code review is the design review. The biggest distinguishing factor is that design reviews happen near the beginning of your work, while code reviews happen at the end. Not all teams require this process. Even if they don’t, it might be a good idea to do it anyway.
This isn’t to say, “always do a design review.” I only wish to point out design reviews’ value and a good tool for effective engineering communication. As a feature’s complexity is greater, the higher probability that a technical design review will prove helpful for the time you spend on it. The design review’s value is to save time; if in doubt and the implementation is straight forward, you may not need to use this tool.
Have you ever published a code review and found it reviewed negatively, asking for large changes to it? Possibly even had to rewrite most of your changes after the fact. Then that is a strong signal that a design review would have helped save everyone time.
What is a design review?
Design reviews can be quite informal and utilize software tools to make it lightweight in the process. It can even be as simple as a brief meeting with those who will likely review the code (and other key stakeholders). The idea is to effectively communicate what you want to build and help others visualize what you want in the final shape.
It can be daunting to get everything your peers expect to be correct by just diving in without communicating your intentions beforehand. Taking the time to document and portray what you want and how to build it will save time in the long run. This is an opportunity to utilize your team’s experienced members and avoid reworking mass portions of your work after being implemented.
Once your team and stakeholders have bought off on your proposed design, filling in the implementation with the established design will be more straightforward. Further, you will have more confidence in what you’re building, including the added benefit that your team knows how it works.
The code review should be consistent with your design. Link to it from your code review. This will leave only the code implementation left for review since the overall architectural shape has been established.
What should you consider in a design review?
Preparing for a design review will help you think about your ideas and plans more thoroughly than if you were to jump in and code. There are a lot of things to consider though, where do you start?
Most importantly, when doing a design review, don’t focus on implementation; that is what code is for. Instead, focus on the high-level concepts. Ask yourself, if a brand new developer joined the team and was tasked to make changes to my feature, what can I document to make them successful? Here are some good things to consider adding to your technical spec below.
- What is the feature anyways? Any particular terminology, domain, or business that one should know.
- Links to any supporting documentation from dependencies (up or downstream), libraries used, UI mocks, etc., with some description of how it is related.
- Break down of sub-tasks needed to complete the feature and associated time estimates (with links to the work items). Also, priorities for each task in the event some tasks need to get cut.
- Brief documentation on why the design is the way it is and decisions made to justify the design.
- Domain diagram on the structure of the feature.
- System diagram if there is a complex system in use with multiple programs.
- Sequence diagram to portray very trick interactions with the system.
- What exposed APIs will there be and their purpose?
- What exposed models will there be, and what is their purpose?
- How do you manually test it to make sure it still works?
- What telemetry and user BI is associated with this, and where is it consumed?
- Are there automated tests, and where do they live?
- What diagnostic logs or tools are useful in this feature area?
Tools to help with design reviews
Some tools can help conduct a design review, but the design review should be more thought-provoking than time-consuming. The tool should provide value by saving you time or making it easier to archive or share. I have seen a simple picture of a whiteboard diagram to be effective enough for the design reviews. PowerPoint diagrams or some more fancy LucidChart graphs could also be great choices for reusable tooling.
UML is a visual design language that makes a standard design language good for high-level technical design. It provides a standard structure for helping communicate. Domain diagrams are the most common and useful tool for design reviews. It describes the top-down structure of what you will build. For complex models that require complex interaction between systems, sequence diagrams can help substantially. Sequence diagrams help understand how the information will flow through external and internal pieces of the system. System diagrams can be useful to understand how an eco-system of several programs interact.
Guidelines to help with design reviews
- Know the change you need to make. If it isn’t a simple modification of existing code, a parity feature, or a non-complex refactor, it’s a good candidate for a design review.
- Keep your design reviews small and concise. Time preparing a design review will depend on the feature’s size and keep it under 2-3 days. It doesn’t need to take more time than necessary; after all, it is a tool to communicate what you want to build and how. From there, it is a conversation about strengthening your design by adding input and experience from your team.
- Sometimes more exact technical specs are necessary over a simple design review. Some teams require a full technical spec that describes, in great detail, the feature’s system and API. If this is the case, abide by your team’s culture and expectations. These are especially beneficial on large cross-team projects. It ensures that your exposed APIs are defined and allows larger organizations to build pieces of the more extensive system around your design before it is done.
- Communicate and visualize. Communicate what you intend to build. Importantly, make sure your team can fully picture the feature’s system and how to use it. The crucial goals of conducting the design review are for the team to be on the same page on what and how it is built. It also portrays what established architectural practices, patterns, or dependency abstractions can be leveraged by your new feature.
Once you achieve buy for your design, you are now free to implement it. Then, open a code review to get feedback on the change. Design reviews are a great tool to forecast change, think about problems holistically, and get good high-level feedback before checking in code.
