A Little Context Can Go A Long Way

Improving the code review process with simple conventions and contextual identifiers.

Code reviews are an extremely important part of the development process, however they can often lack the context for everyone involved to have great experience and get optimal value.

There are a number of ways that code reviews are generally valuable:

1. They help validate the work that you have done so that you feel more confidence in its correctness before deploying to production.
2. They are an opportunity to learn/teach and share experience, wisdom and alternate points of view.
3. Most importantly, they are means of producing better code and a better end product.

However this value can easily be derailed if you leave a flood of comments on the code without the setting context and expectations. This can sour the process for all parties involved. I experienced this first hand when I starting at a new company and wanting to immediately add value by doing thorough code reviews for people. When we talked through the resulting frustration it became clear that context was the main problem, and rather than relying on either tribal knowledge or perceived tone, as a means of interrupting a comment we should instead create a consistent set of shortcuts that could ensure consistent context and interpretation across the engineering org.

The result was a set of tags, that we started prefacing comments with. Each tag has both an implication and an expectation associated with it to help contextualize the intent and set expectations about the response desired.

Code Review Contextual Conventions

These have proved extremely useful in my day to day work and spurred interest from everyone I talked about them with. Hopefully these conventions can now provide value to others as well. I would love to hear about others experience in this area and any suggestions for additions or improvements.

Thanks to Kevin, Manu and all the other engineers that helped refine this rubric.