Software Engineering
version-control
Updated Mon, 01 Aug 2022 14:28:39 GMT

Should commit messages be explicit by themselves, without requiring a diff?


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 diff results.

So:

Should a log message of a commit be explicit by itself, without requiring a developer to explore the diff in order to understand it?

Solution

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 'diff'.

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.

Comments (4)

  • +0 – "Sometimes, a commit is just too large": doesn't it defeat the purpose of a commit (and a version control system in general)? — Jul 23, 2016 at 23:23  
  • +1 – @MainMa Merge commits can be very large even if its parts are small. — Jul 23, 2016 at 23:57  
  • +1 – @Doval: valid point. — Jul 23, 2016 at 23:58  
  • +0 – +1 for changing from "why" to "what", and then add some reference to a bug tracking system, which explains the why. — Aug 23, 2016 at 07:29  

References