Effective Code Reviews with Conventional Comments • Paul Slaughter & Adrienne Braganza
Paul Slaughter, creator of Conventional Comments, and Adrienne Braganza Tacke discuss how a structured, empathetic approach to feedback can transform code reviews from frustrating processes into productive collaborations. They explore the philosophy behind labeling comments, the importance of fostering collaborative ownership, and practical strategies for maintaining both politeness and efficiency in asynchronous, remote environments.
In a conversation with Adrienne Braganza Tacke, Paul Slaughter, a Staff Fullstack Engineer at GitLab, delves into the origins and philosophy of “Conventional Comments,” a system designed to improve the clarity and empathy of code review feedback.
The Genesis of Conventional Comments
The idea for Conventional Comments grew organically from Paul’s experiences at GitLab, a fully remote and asynchronous company. Working with a global team where English is not everyone’s first language highlighted the potential for misinterpretation and frustration in code reviews. Comments like “it shouldn’t be done this way” were confusing and lacked actionable direction.
To combat this, Paul focused on overcommunication and making his intent crystal clear. He wanted to eliminate the room for self-critical misinterpretation by the author. This led to the practice of labeling comments to explicitly state their purpose. The structure was heavily inspired by Conventional Commits, providing a familiar format for engineers.
“I’ve really kind of narrowed in and like there’s like fiveish labels that all of my comments kind of orbit around. I’m always leaving a suggestion, highlighting an issue or asking a question… it’s really helpful for me to give myself a constraint in that way so that we’re not also just holding up merge requests from this very vague open-ended discussion.”
Core Labels and Expressive Communication
While the Conventional Comments website lists several labels, Paul primarily gravitates towards three for about 90% of his feedback:
- suggestion: Proposing a change.
- issue: Highlighting a problem, often a bug or a broken feature.
- question: Seeking clarification.
He often uses decorations like (non-blocking) to further clarify the urgency. Beyond these, Paul advocates for using more expressive labels to match the specific context. For instance, polish is a softer alternative to nitpick for minor improvements, while brainstorm or thought can be used to open up a non-blocking, collaborative discussion about future possibilities sparked by the code. Sometimes he pairs labels, first identifying an issue and then following up with a suggestion that includes a patch to fix it.
Fostering Collaborative Ownership and Empathy
A key theme is shifting the posture of code review from a gatekeeping process to a collaborative one. Paul emphasizes that the goal is for the reviewer and author to co-own the code.
“When I’m submitting code, I’ve got to realize, yeah, this isn’t this is ours. And it’s going to be a lot better when we can all co-own it.”
This mindset challenges the common but sometimes harmful advice to “not take comments personally.” While there’s wisdom in not letting feedback define one’s self-worth, it’s a mistake to ignore the fact that developers are emotionally invested in their work. A team that cares deeply about its product will naturally have feelings connected to it. Dismissing this emotional component can lead to a culture where feedback feels like constant criticism rather than constructive collaboration. The labels in Conventional Comments serve as a gentle reminder to maintain a constructive, curious posture.
Normalizing the Review Experience at GitLab
To address the problem of inconsistent review experiences across a large, distributed team, GitLab initiated “Code Review Weekly Workshops.” These publicly recorded meetings serve as an open forum for engineers to:
- Discuss challenging or exemplary code review interactions.
- Share best practices and efficiency hacks.
- Normalize the review experience for all contributors.
The workshops provide a space to learn from real-world scenarios in a non-blaming, curiosity-driven environment. It’s a way to continuously discuss and refine the collaborative process, helping to grow the number of maintainers and break down knowledge silos.
Balancing Politeness with Efficiency
Paul strongly pushes back against the false dichotomy that politeness and efficiency are mutually exclusive. He argues that you can, and should, be both. Two key tactics he uses to maintain efficiency are:
- Using Patches: Instead of leaving numerous small comments for minor changes, he reviews the code locally, generates a single patch, and includes it in one comment (e.g.,
polish: Here's a patch with some minor cleanups...). This is far more efficient for the author, as it requires less cognitive load to parse and apply than multiple individual comments. - Setting a Timer: He sets a timer for his reviews. After a certain period, he finds the value of his feedback diminishes, and he starts asking more questions instead of providing actionable suggestions. This self-imposed constraint keeps the review focused and productive.