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
diff would 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?
IMHO, no. Sometimes, a commit is just too large to be explained in enough detail in the message, for it not to require exploring the '
However, I would change the why to a what (described in broad strokes). This way, a developer can get a good idea of what was affected by that commit, and only have to explore the
diff if they really want to go into detail.
As for the why, if you're using some sort of bug tracking system, I would reference the issue number in the commit message. If not (unlikely), it's best to mention the why in broad strokes as well.