Code Review Comment Prefixes for Clearer Feedback

We are always trying to find new or better ways to improve our development processes. Sometimes, even minor changes can result in a more streamlined approach to help our team collaborate better while avoiding miscommunications.

One simple change we've implemented is our own standardized set of prefix review terms to use in comments when leaving feedback during code reviews. We - did - not - invent - this. However, we have implemented this idea in our own way and found that it works for us.

Code Review Prefixes You Can Try

We use the following comment prefixes. Consider what prefixes would work for your team and modify their implementation as necessary.

Callout

• When we bring new insights to the table, it's only sometimes with the intent of immediate action. Often, it's about enriching our collective understanding.
• We use this prefix to provide additional context to other reviewers. Generally, this information is only useful in the context of the review itself (e.g., ”This block is going to be removed in the next PR”) — otherwise, it should be turned into a code comment or line in the commit message.

FYI or Nofix

• There are moments when we have knowledge that, while not urgent, is too important not to share.
• We use this prefix when we think it would be best if the author held off on any changes for now to conserve time, but there is some information that could be beneficial for future reference.

Check

• It's essential to pause and reflect on different scenarios, even if they don't lead to immediate action.
• We want to encourage a moment of consideration, not necessarily implying a need for a change but assessing whether the author has considered a particular scenario or whether a change you made was intentional.

Optional

• This comment suggests a change, but it's entirely optional and subject to what you deem best.
• We believe in letting code authors write the code. As a reviewer, it’s hard to tell if your suggestion is actually helpful or more stylistic. Marking a comment as optional allows the author to make that call.

Nit or Super Nit

• For either of these, a change is required, but we acknowledge that the change is minimal and somewhat of a nitpick.
• We point these changes out as an opportunity to enhance the overall quality of our work. These minor tweaks often elevate our work from good to great.

Blocking

• These are the non-negotiables that are currently hindering the approval of the requested changes. These issues need to be addressed first.

Why Implement Comment Prefixes?

Consider this scenario: You've been working to implement a new feature, and it's almost ready for primetime. You finally submit a pull request… and get a lot more feedback than you expected. You're not sure where to start or what to prioritize. Some comments are real problems you need to address, some are just more ideas to consider, and for a few comments, it's unclear what action you need to take. This is where strategically prefixing review comments comes into play.

Starting each comment with a prefix of an acceptable outcome makes it clear what needs to happen. It takes fewer words and enables the reader to see the intention of the comment at a glance. This helps all parties communicate better and implement the changes as needed in the right ways. It's simple, and it works.

If you liked this post, you should read our full blog on How We Do Source Control at Doppler.

You should experiment with these review terms and determine what works for your team. Make sure to share what's working for you with others. Feel free to email chandler.mayo@doppler.com about how you use comment prefixes for code review or why you don't. We'd love to hear from you.