TIL Conventional Comments
I love it when I find things that seem obvious after discovering them, but I had no idea they existed before. I’ve been reading Looks Good To Me by Adrienne Braganza. Looks Good To Me is often abbreviated LGTM and is used as short-hand in the code review process when one programmer is reviewing the code of another before that code is accepted into a code base. This is meant to be part of a system of checks and balances to ensure code quality.
Software changes constantly; change is the norm in software development. When a programmer changes the code, it is checked into a version control system, such as git, so that changes can be tracked over time. To ensure that the changes are those reviewed by other programmers, the programmer first makes a branch of the code they want to change, then makes their updates, and then creates a pull request to be reviewed by others. Unlike auto-save on most consumer software, programmers choose when to commit their code. You can think of committing as a snapshot of your saved files in time. When you commit this code, you also write a commit message. This can technically be anything, but many folks (self-included) prefer structured commit messages called conventional commits.
Conventional Commits are “a specification for adding human and machine-readable meaning to commit messages.” What is nice about these is that they remove ambiguity from the commit message and have the added benefit of being machine-readable, so you can even use programs that read the commits and help perform actions or generate reports.
In Looks Good To Me, I discovered a standard called Conventional Comments meant to help standardize writing meaningful and easy-to-understand comments in a code review process. Influenced by Conventional Commits and the Google Engineering Practices guide, this extends two great ideas into something that makes a standard process (code reviews) more direct and well-structured by extending an existing convention into a new domain.
It’s a beautiful idea in its simplicity, and I can’t wait to start using it in my code reviews.
Links this Week
Discussion of Building Evolutionary Architectures (part 2) is out
Carl Brown of Internet of Bugs shares his favorite books on Book Overflow
Popcat vs Vibe Cat, if you know, you know
Can you tune a Fish? turns out you can.
Shrimp Quartet. Oh, internet.
The NSA released a two part video lecture by Grace Hopper. Must watch.