Conventional comments

Conventional comments are a standardized way of annotating code reviews to provide clear, structured, and easy-to-understand feedback. This method categorizes comments to clarify their intent, urgency, and required actions, making the review process more transparent and efficient. 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

Conventional comments break down feedback into several components to quickly convey its nature and importance:

1. Label: Keywords like question, nitpick, suggestion, issue, or praise indicate the type of comment.
2. Politeness: A polite phrase to ensure feedback is seen as constructive.
3. Explanation: A brief reason for the comment, providing insight into the reviewer’s perspective.
4. Action: A suggested action or a note if no action is needed.

Example of a conventional comment

Consider this example:

• [Nitpick (non-blocking)]: I'm wondering if it would be more transparent to rename the variable userCount. The abbreviation uc might be unclear.

This example highlights the benefits of conventional comments:

• [Nitpick] marks the feedback as minor, indicating it’s not a blocker.
• (non-blocking) implies that resolving this is not a prerequisite for progress.
• I'm wondering if adds a touch of politeness to the suggestion.
• The rationale is clear—userCount is more descriptive than uc.
• The action is an optional change: consider a rename.

Advantages of conventional comments

• Clarity: They ensure feedback is understandable for both the reviewer and the developer.
• Efficiency: They streamline the review process by minimizing unnecessary communication.
• Learning: They help developers learn best practices and understand the rationale behind coding decisions.
• Consistency: They standardize the feedback across various reviewers and teams.
• Focus: By categorizing feedback by severity and type, developers can prioritize the most crucial issues.

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.