Conventional: Comments

⚓ About

❌ Bad review comment

Most of the time comments like this are unhelpful…

✅ Good review comment

By simply prefixing the comment with a label, the intention is clear and the tone dramatically changes.

🏆 Better review comment

Labels also prompt the reviewer to give more actionable comments.

🚧 Conventional comment format

Consistent format improves reader’s expectations and actions

<label> [decorations]: <subject>[discussion]

🔖 Labels

🎊Decorations

Decorations give additional context for a comment. They help further classify comments which have the same label (for example, a security suggestion as opposed to a test suggestion)

🥇 Best Practices

  1. Leave actionable comments
  2. Combine similar comments
  3. Replace “you” with “we

📑 Saved replies Github

💻 Conventional Comments Buttons Extension

I have created a chrome extension to quickly add conventional comments to GitHub pull requests comments which we can install and use from here Conventional-Buttons

Conventional comments extension

📑 Conclusion

Conventional comments are Practices, I find it to be a good practice. Here are a few reasons.

  1. The separation between the topic of the comment and the example and/or reasoning of the comment is very clear and straight
  2. The author knows what they should prioritize because our comments are well-labeled

🔗 References

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Abdallah Hemdan

Abdallah Hemdan

Frontend Software Engineer@Instabug