I recently received some advice that the summary line of a Git commit message should describe what the change does. In particular, they said to avoid summaries in the form of “Fix <broken thing>”.
For example, instead of “Fix wrong default font for FooComponent on BarPlatform”, write “Explicitly inherit BazComponent font for FooComponent on BarPlatform”. Or instead of “Optimise FooFunction memory use to improve performance”, write “Reuse existing heap allocations on BarObject in FooFunction”.
On the one hand, I can see that writing summaries this other way communicates more specific detail about what changed; “Fix <broken thing>” could mean anything happened. On the other hand, what the change does is already described by the code, so focusing the summary on why the change was made instead seems much more beneficial.
This is probably more of a ‘spaces versus tabs’ kind of thing where the answer doesn’t matter too much, but I am curious to hear from others on which approach you have found most beneficial in your work. In particular, if anyone uses this style of “describe the change” summarisation, have you experienced any particular benefits that might not be obvious? Thanks!
Yes.
Intent first, then a high level summary of the changes (if non-trivial).
Some programmers say that the code is the documentation and that comments in code are a "code smell". I strongly disagree.
The code is a communication between the programmer and the compiler, and leaves out intent. The code does what it does, right or wrong. But what we care about is what we intended the code to do, and why.
So intent is more important because the code could be wrong.