I have noticed that I recently wrote the following commit message:
Since HTML changed, getting the index would always result in zero, since the element is now enclosed in a parent block.
For someone who starts by viewing the
diff of the commit commit first (for instance after doing a
blame on a file) and doesn't get the purpose of the change, this message is helpful:
It tells why the change within the commit was done, not what was the change (a
diffwould tell what the change actually is).
It explains the larger picture, the context in which the commit was done.
However, for someone who is simply browsing the log, the message is absolutely cryptic. What HTML? What index? What parent block? What the heck is happening here? In order to figure this out, the person should need to
diff the changes, and only then she will understand the message. It doesn't even matter if the person knows the project; I'm pretty sure I won't be able to explain the message myself in a week without consulting the
Should a log message of a commit be explicit by itself, without requiring a developer to explore the
diff in order to understand it?