Conventional comments

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.

Structure of Conventional Comments

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.

Example of a Conventional Comment

• [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.

Advantages of Conventional Comments

• 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.