I’m sure you’ve heard about conventional commits, but what about conventional comments?
The Problem
Code Reviews can go terribly wrong. They're quite a delicate aspect of our daily job and require trained skills and mindset to approach them the right way.
It is so easy to get misunderstood and start pointless discussions, often overlooking critical aspects instead.
I recently discovered a tool, that is in fact a set of rules, to help focus on what really matters and avoid arguments and wasting of time.
Conventional Comments
The idea is similar to conventional commits, adding labels, decorators and context to your comments.
Something like this:
<label> [decorations]: <subject>
[discussion]
Labels
This is relly similar to conventional commits, a label to define the type of the comment. It can be a suggestion, a praise, a nitpick or a proper issue.
Decorations
Here you can make a more defined scope, for example if the comment is an issue and it is about the performance, your comment might look like this:
issue(performance)
Subject
A short summary of your comment, basically what you would write in the title of an issue.
Following the previous example:
issue(performance): This can cause an endless loop of re-renders
Discussion
However, this might still seem sharp or a bit too vague, that's why you might need to add an extra discussion or actionable item to make it more clear and prevent possible follow-up questions.
issue(performance): This can cause an endless loop of re-renders
Do we need this in the dependency array? We can achieve the same result by moving it to Line 67.
Conventional Comment specification
This was a brief introduction to the concept, but there is a full specification available at conventionalcomments.org.
You can find all the details on that page and I also recorded myself while scrolling through it and commenting it live, you can watch it in the video below:
Thanks for reading this article, I hope you found it interesting!
I recently launched a GitHub Community! We create Open Source projects with the goal of learning Web Development together!
Join us: https://github.com/DevLeonardoCommunity
Do you like my content? You might consider subscribing to my YouTube channel! It means a lot to me ❤️
You can find it here:
Feel free to follow me to get notified when new articles are out ;)
Top comments (9)
this is really nice, but if there was something like an IDE extension for vscode that can help give these comment conventions snippets easily, people can then use this convention more, I also started to use conventional commits only when I met this tool: github.com/Everduin94/better-commits I wish something too for comments but not a CLI just an extension perhaps!
That's a really good idea! As of today we have the official vscode extension where you can review PRs but I don't think we can request to add conventional comments there.
I don't know if it's actually possible to build something third-party on top of that though, it would be nice!
Well please do work around it, there already some comment extensions out there but they don't fully have a known convention, for example I use better comments, it just highlights comments depending on keywords I use in the comment, then comment anchor helps me track comments across codebase etc, these little things make dev life happier!
I'm a big fan of conventional comments. 👏
Great! I'm going to use it at work and see what happens :D
I used Conventional Comments for a past client and noticed that slowly other team members started to use it too.
Maybe I should try conventional comments. Thanks for this! 👏
Definitely worth a try :D
Thank you so much for the solution. Dear student, do you need help with your academic papers? I am sharing my gem with you all, which is canadianwritings.com/ CanadianWritings. Their team of experienced writers can assist with essays, research papers, dissertations, and more. I've used their services and was impressed with the quality of work and their professionalism. Highly recommend!