Enhancing Code Reviews with Conventional Comments
TSOTSI1
Posted on June 11, 2023
In software development, code reviews are a vital practice that ensures code quality, promotes consistency, and fosters knowledge sharing. Yet, at times, they can drive me absolutely bananas!
However, the effectiveness of code reviews is contingent on clear, concise communication. This is where Conventional Comments play a pivotal role.
Conventional Comments provide a standardized method of delivering and receiving feedback during code reviews, reducing misunderstandings and promoting more efficient discussions.
What are Conventional Comments?
Conventional Comments are a structured commenting system for code reviews and other forms of technical dialogue. They establish a set of predefined labels, such as nitpick, issue, suggestion, praise, question, thought, and notably, non-blocking. Each label corresponds to a specific comment type and expected response.
Labels instances:
| Labels | Description |
|---|---|
| praise | Highlights something positive. Always look for something to sincerely praise. |
| nitpick | Trivial, preference-based requests. These should be non-blocking by nature. |
| suggestion | Proposes improvements to the current subject. Be explicit and clear on what is being suggested and why it is an improvement. |
| issue | Highlights specific problems with the subject under review. These problems can be user-facing or behind the scenes. It is strongly recommended to pair this comment with a suggestion. |
| todo | Small, trivial, but necessary changes. Distinguishing todo comments from issues or suggestions helps direct the reader's attention to comments requiring more involvement. |
| question | Appropriate if you have a potential concern but are not quite sure if it's relevant or not. Asking the author for clarification or investigation can lead to a quick resolution. |
| thought | Represents an idea that popped up from reviewing. These comments are non-blocking by nature, but they are extremely valuable and can lead to more focused initiatives and mentoring opportunities. |
| chore | Simple tasks that must be done before the subject can be “officially” accepted. Usually, these comments reference some common process. |
| note | Always non-blocking and simply highlight something the reader should take note of. |
| typo | Typo comments are like todo:, where the main issue is a misspelling. |
| polish | Polish comments are like a suggestion, where there is nothing necessarily wrong with the relevant content, there's just some ways to immediately improve the quality. |
| quibble | Quibbles are very much like nitpick:, except it does not conjure up images of lice and animal hygiene practices. |
Decoration instances:
| Decoration | Description |
|---|---|
| non-blocking | A comment with this decoration should not prevent the subject under review from being accepted. This is helpful for organizations that consider comments blocking by default. |
| blocking | A comment with this decoration should prevent the subject under review from being accepted, until it is resolved. This is helpful for organizations that consider comments non-blocking by default. |
| if-minor | This decoration gives some freedom to the author that they should resolve the comment only if the changes end up being minor or trivial. |
For instance, a suggestion tag signifies a possible improvement proposed by the reviewer, but it isn't obligatory. On the other hand, an issue tag denotes a problem that needs rectification.
The non-blocking tag is used to indicate a comment that should not prevent the code from being merged, but which the author might consider addressing.
How do Conventional Comments Elevate Code Reviews?
1. Improving Clarity in Communication
By standardizing labels and formats, Conventional Comments enhance the clarity of comments, eliminating vague language and misunderstandings, ensuring all participants understand the intent and meaning of the comments.
For instance, if a reviewer writes: "issue: This function might cause a memory leak.", the developer immediately recognizes a problem that requires fixing rather than a simple suggestion or consideration.
2. Providing Structured Feedback
Conventional Comments facilitate a way to organize and structure comments, making code reviews more efficient and aiding developers in understanding and responding to feedback faster.
For instance, a praise comment can directly link positive feedback to a specific piece of code, while a thought comment can propose ideas that might warrant further discussion.
3. Encouraging Open and Constructive Dialogue
Conventional Comments foster open and constructive conversations. By explicitly labeling the type of comment, developers can better understand the nature and intent of the feedback, leading to increased confidence in participating in the review process.
For example, a suggestion comment sparking a deeper discussion could lead to improvements in the code or design and enhance knowledge sharing among the team.
Conclusion
Conventional Comments makes code reviews more effective and productive.
By adopting this structured commenting approach, development teams can improve clarity in communication, provide more structured feedback, and foster open, constructive conversations.
Both reviewers and reviewees stand to benefit from the implementation of Conventional Comments. Happy coding🤘!
Reference: https://conventionalcomments.org/
Posted on June 11, 2023
Join Our Newsletter. No Spam, Only the good stuff.
Sign up to receive the latest update from our blog.
Related