I agree with the value of searching the commit history, but I think the author’s example is a bad one.
They documented the decision to access a field for seemingly no reason, but they put the documentation in the wrong place. I can understand if they said, “Whoops, I was in a rush and forgot to document that,” but they took the time to document it in the commit message when it belonged in the code itself.
It’s like saying, “I often put my plates in my cutlery drawer, so if you ever can’t find a plate, check your cutlery drawer.” But the better solution is to just learn not to put plates in the cutlery drawer.
Comments are useful, especially for strange changes, but commit messages stay bound to the code they introduce long after surrounding code has been modified (and comments possibly changed or removed). It is better to write a commit message and no comment than a comment and no commit message.
For code like the article’s .clientLeft example, an explanation in an adjacent code comment strictly dominates an explanation in the commit message.
If it’s in a code comment, anyone seeing the code will see the explanation without having to dig through the source history. Even if someone messes up and deletes or disassociates the comment from the relevant code, the comment as it originally existed would be in the source history anyway.
If someone has to do git archeology to find the original commit message for a line, they’d see the code with its original comment anyway, so the explanation is better in the code.
Is there a scenario where putting an explanation for confusing code in the commit message reaches the relevant reader when a code comment wouldn’t?
No. However, a review of the history and the context of the change has - in my experience - been required viewing in all cases where such a comment exists (or doesn’t). In other words, I have to go to the history anyway. I’ve never cursed someone for writing a thorough commit message. I have cursed someone for writing a thorough comment and providing no context in the commit that added it.
I agree with the value of searching the commit history, but I think the author’s example is a bad one.
They documented the decision to access a field for seemingly no reason, but they put the documentation in the wrong place. I can understand if they said, “Whoops, I was in a rush and forgot to document that,” but they took the time to document it in the commit message when it belonged in the code itself.
It’s like saying, “I often put my plates in my cutlery drawer, so if you ever can’t find a plate, check your cutlery drawer.” But the better solution is to just learn not to put plates in the cutlery drawer.
Comments are useful, especially for strange changes, but commit messages stay bound to the code they introduce long after surrounding code has been modified (and comments possibly changed or removed). It is better to write a commit message and no comment than a comment and no commit message.
For code like the article’s
.clientLeftexample, an explanation in an adjacent code comment strictly dominates an explanation in the commit message.If it’s in a code comment, anyone seeing the code will see the explanation without having to dig through the source history. Even if someone messes up and deletes or disassociates the comment from the relevant code, the comment as it originally existed would be in the source history anyway.
If someone has to do git archeology to find the original commit message for a line, they’d see the code with its original comment anyway, so the explanation is better in the code.
Is there a scenario where putting an explanation for confusing code in the commit message reaches the relevant reader when a code comment wouldn’t?
No. However, a review of the history and the context of the change has - in my experience - been required viewing in all cases where such a comment exists (or doesn’t). In other words, I have to go to the history anyway. I’ve never cursed someone for writing a thorough commit message. I have cursed someone for writing a thorough comment and providing no context in the commit that added it.