DEV Community

Cover image for Enhancing Code Reviews with Conventional Comments
TSOTSI1
TSOTSI1

Posted on • Updated on

Enhancing Code Reviews with Conventional Comments

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!

Image description

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🤘!

Image description


Reference: https://conventionalcomments.org/

Top comments (0)