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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

commit 0d5914ca843b0129ceca84f5b0d9f6635f6dd93b
Author: Sloppy Coder <[email protected]>
Date:   Wed Mar 27 18:00:00 2019 +0100

    Fixes bug

commit 42038779e6f6eb39f491023f7ef709feec669209
Author: Sloppy Coder <[email protected]>
Date:   Wed Mar 27 18:10:04 2019 +0100

    Tweaked styling

commit 0cd47fec087cc39088bad9646fc7acf01ff7c372
Author: Sloppy Coder <[email protected]>
Date:   Wed Mar 27 18:15:08 2019 +0100

    Refactor

commit b51aff339e0aa9c91498140c310c55871edaacf5
Author: Sloppy Coder <[email protected]>
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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

commit ee46b9b44fb5e2bca2344ceb3288964a09f72910
Author: ayazhafiz <[email protected]>
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 <[email protected]>
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 protected]>
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.