As a software engineer, attention to detail is key because one small typo in your code can cause catastrophic bugs. Code isn't the only artefact software engineers produce, though. For example, most of us create numerous commits every day. Each commit includes a commit message describing the changes. I argue the same attention to detail that is necessary to write high quality code should be extended to many other things a software engineer does, including writing commit messages.
Investing the small amount of time necessary to write great commit messages brings many benefits. The reason is simple: a good software development process is all about communication. Commit messages can communicate intent and motivations which can't be deduced from the code changes.
Going a step further, defining rules about the way commit messages have to be written allows programmatic processing. For example, changelogs and semantic versioning can be automated. Furthermore, a consistent commit history makes it easier for humans to interpret the history. This facilitates faster code reviews and benefits new hires that neeed to familiarize themselfes with an existing codebase. The advantage of additional context such as ticket references is obvious.
Consider the following commit history:
commit 0d5914ca843b0129ceca84f5b0d9f6635f6dd93b Author: Sloppy Coder <email@example.com> Date: Wed Mar 27 18:00:00 2019 +0100 Fixes bug commit 42038779e6f6eb39f491023f7ef709feec669209 Author: Sloppy Coder <firstname.lastname@example.org> Date: Wed Mar 27 18:10:04 2019 +0100 Tweaked styling commit 0cd47fec087cc39088bad9646fc7acf01ff7c372 Author: Sloppy Coder <email@example.com> Date: Wed Mar 27 18:15:08 2019 +0100 Refactor commit b51aff339e0aa9c91498140c310c55871edaacf5 Author: Sloppy Coder <firstname.lastname@example.org> Date: Wed Mar 27 18:21:44 2019 +0100 Stuff
These commit messages aren't helpful because they don't contain any useful information. Compare this with the Linux' commit history. Every commit message explains the changes and motivations in great detail. An example for commit messages that follow a set of rules is Angular's commit history which uses the Conventional Commits style. Go ahead and read the Conventional Commits specification for inspiration, it is quite short. This is how Angular's commit history looks like:
commit ee46b9b44fb5e2bca2344ceb3288964a09f72910 Author: ayazhafiz <email@example.com> Date: Fri Dec 20 14:26:27 2019 -0600 fix(language-service): correctly parse expressions in an attribute (#34517) Currently, the language service provides completions in a template node attribute by first checking if the attribute contains template bindings to provide completions for, and then providing completions for the expression in the attribute. In the latter case, the expression AST was being constructed "synthetically" inside the language service, in particular declaring the expression to be a `PropertyRead` with an implicit receiver. Unfortunately, this AST can be incorrect if the expression is actually a property read on a component property receiver (e.g. when reading `key` in the expression `obj.key`, `obj` is the receiver). The fix is pretty simple - rather than a synthetic construction of the AST, ask the expression parser to parse the expression in the attribute. Fixes https://github.com/angular/vscode-ng-language-service/issues/523 PR Close #34517 commit c079f38cbba19fe3953e70957ea93259070b5c13 Author: Keen Yee Liau <firstname.lastname@example.org> Date: Thu Dec 19 18:33:26 2019 -0800 feat(language-service): Show documentation on hover (#34506) This commit adds dpcumentation to the hover tooltip. PR closes https://github.com/angular/vscode-ng-language-service/issues/321 PR Close #34506 commit ba2fd31e62cdbe4a22941fa4c26ff7f84f3a1d64 Author: ivanwonder <email@example.com> Date: Thu Dec 19 11:10:09 2019 +0800 fix(language-service): The pipe method should not include parentheses (#34485) PR Close #34485
I won't argue for a certain style, but consider the benefits of great commit messages in general, especially if the code base is large or development is expected to continue for a long time. Ideally, the chosen convention is enforced automatically in CI/CD and with git hooks.