thought: On writing better comments
Landed upon this page today from one of my internet rabbit holes: https://conventionalcomments.org/
It's a page dedicated toward establishing a guideline for writing better comments, whether for code review, peer review, revising, etc.
I find the format to be very similar to a Github commit. There are many resources that teach about writing better git commits so that it follows the practice for writing better commit messages for other developers. Learning to write better commit messages can be daunting but is a skill needed for more effective online collaboration, especially in the open-source software world (e.g. issues, PRs).
Today I realized that this practice can be applied for many other forms of content sharing.
According to conventionalcomments.org, this is their format:
<label> [decorations]: <subject>
[discussion]
By this convention, a Github commit message is a form of comment for changes with actionable items.
Having consistency is nice. If things are more formatted this way, we will have structured data, and contents can be more easily extract-able and stored for knowledge base.
I'm excited too see more stuff about this labeling convention across the internet, beyond the developer community :)