Conventional comments

Greg Foster
Greg Foster
Graphite software engineer


Note

This guide explains this concept in vanilla Git. For Graphite documentation, see our CLI docs.


Conventional comments are a standardized way of annotating code reviews to provide clear, structured, and easy-to-understand feedback. This methodology aims to categorize comments in a way that communicates the intent, urgency, and required action effectively. Here's a breakdown of how conventional comments work and why they can be a valuable addition to the code review process.

A conventional comment typically includes the following components:

  1. Label: This is a keyword that quickly indicates the nature of the comment, such as question, nitpick, suggestion, issue, or praise.

  2. Politeness: A polite phrase that ensures the comment is received as constructive feedback, not as a command or criticism.

  3. Explanation: A brief explanation of why this comment is being made, providing context and reasoning behind it.

  4. Action: Suggesting a clear action, if one is needed, or indicating that no action is necessary.

  • [Nitpick (non-blocking)]: I'm wondering if it would be better to name this variable userCount for clarity. It's not immediately clear what uc stands for.

Here's why this is effective:

  • [Nitpick] labels the comment as minor, indicating that this is not a blocker for approval.

  • (non-blocking) further clarifies that this issue doesn't need to be resolved for the work to proceed.

  • I'm wondering if is the politeness component, softening the suggestion.

  • The explanation is that userCount is clearer than uc.

  • The action is implied — consider renaming the variable, but it's optional.

  • Clarity: They provide clarity both for the reviewer, in terms of thought process, and for the developer, in understanding the feedback.

  • Efficiency: They can speed up the review process by reducing back-and-forth communication.

  • Learning: They can be a learning tool, helping the developer understand best practices and the reasoning behind certain coding standards.

  • Consistency: They help maintain a consistent review style across different reviewers and teams.

  • Focus: By labeling the severity and type of each comment, they help the author focus on the most important issues first.

Incorporating conventional comments into your team's code review practices can enhance the quality and effectiveness of code reviews. It can also help in building a more positive and productive code review culture, where feedback is clearly communicated, and developers understand exactly what is expected of them.

Git inspired
Graphite's CLI and VS Code extension make working with Git effortless.
Learn more

Graphite
Git stacked on GitHub

Stacked pull requests are easier to read, easier to write, and easier to manage.
Teams that stack ship better software, faster.

Or install our CLI.
Product Screenshot 1
Product Screenshot 2