Better feedback in Code Reviews with Conventional Comments

In software development, clear and constructive feedback is essential for maintaining high-quality code and fostering collaboration among team members. One method that has gained traction in modern development workflows is Conventional Comments.

In this article, we’ll cover how these structured comments help streamline code reviews, making feedback more actionable and easier to understand.

Enjoy!

🤔 What Are Conventional Comments?

Conventional Comments are a standardized way of giving feedback on code during reviews. They use predefined keywords to categorize the nature of a comment, ensuring clarity and consistency. Using Conventional Comments comes with following advantages:

• Improved clarity: The standardized format makes comments easier to interpret.
• Actionability: Developers can immediately understand what needs to be changed.
• Consistency: Team members adopt a uniform style for code reviews.
• Efficiency: Structured comments speed up the review process.

This approach helps both the reviewer and the recipient quickly identify issues, suggestions, or praise in the review process. To adopt Conventional Comments effectively:

1. Educate your team – Ensure everyone understands and follows the format.
2. Integrate into code reviews – Use them in pull requests and peer reviews.
3. Automate where possible – Some tools allow for templates and comment suggestions.
4. Encourage constructive feedback – Keep the comments clear, respectful, and helpful.

🟢 Common Conventional Comment Keywords

Below, you can see a list of keywords you should use to implement Conventional Comments in your workflow:

1. suggestion: - Proposes an improvement or alternative approach.

   • Example: suggestion: Consider using a loop here for better scalability.

2. question: - Seeks clarification or requests more context.

   • Example: question: Why did you choose this algorithm over another?

3. issue: - Highlights a bug, security flaw, or functional problem.

   • Example: issue: This function does not handle null inputs properly.

4. nitpick: - Points out minor stylistic or formatting concerns.

   • Example: nitpick: Consider using single quotes for consistency.

5. praise: - Recognizes well-written code or a good decision.

   • Example: praise: Great job optimizing this function!

6. thought: - Offers a general idea or discussion point without necessarily requiring action.

   • Example: thought: Would it be beneficial to modularize this function?

7. todo: - Notes an action item to be addressed later.

   • Example: todo: Refactor this function to reduce complexity.

Let's take a look at the following example to see it in more details:

// issue: This function does not handle empty arrays.
function calculateAverage(numbers) {
    return numbers.reduce((sum, num) => sum + num, 0) / numbers.length;
}

// suggestion: Consider adding a check for an empty array to avoid division by zero.

For more examples, checkout Conventional Comments website.

📖 Learn more

If you would like to learn more about Vue, Nuxt, JavaScript or other useful technologies, checkout VueSchool by clicking this link or by clicking the image below:

It covers most important concepts while building modern Vue or Nuxt applications that can help you in your daily work or side projects 😉

✅ Summary

Conventional Comments bring structure and efficiency to code reviews, helping developers communicate feedback more effectively. By using predefined comment types, teams can reduce confusion, improve code quality, and foster a more productive review process. Consider adopting this approach in your next code review to see the benefits firsthand!

Take care and see you next time!

And happy coding as always 🖥️