2012-12-03
A reason for detailed commit messages: as a guard against errors
There's lots of common reasons to write good descriptive commit messages in your version control system. But I've recently come to realize a somewhat unusual reason why they matter; writing good commit messages makes it much more likely that you'll be able to recognize and recover from inadvertent modifications. In theory inadvertent modifications should never make it into your commits. In practice this is always a risk and it happens periodically. Now suppose that you are coming back to the modification after the fact and you've tracked an oddity or a potential problem to part of a commit. How do you know whether this is a deliberate, intended modification or if it was an inadvertent one that snuck in to the commit by accident?
(You can't simply revert the odd modification because you don't know if it's actually part of solving a real problem. If it was and you revert it you've just reintroduced a problem, possibly an obscure one.)
The more generic the commit message is, the less real clues it gives you about this (note that things like bug numbers or 'fixed problem <X>' are mostly generic here). With a generic commit message you have to basically reverse engineer the whole change (including the specific modification you've spotted) to see if it's a plausible solution to whatever problem it's theoretically supposed to be solving and even if you do, you may be left with uncertainty. But if the commit message is specific about what the commit includes (and why) you have a much better chance of knowing that the modification you're looking at is an inadvertent modification, that it has nothing to do with what's supposed to be in the commit (and thus the fix or change the commit is making) and snuck in by accident somehow. Conversely if the modification is mentioned in the commit message you know that it was definitely intentional (although it still may be mistaken).
(Much the same logic applies if the whole change is not a good one, but I'm assuming that you don't have those because people don't commit stuff that is significantly bad.)
This is probably less of an issue for code and thus programmers than for the sort of configuration and control files that sysadmins tend to deal with; code is in a way often more understandable on its own than a configuration file change is. Especially opaque are what I'll call 'factual' changes, which have no clues about what they're trying to achieve; the classic factual change is a permissions change, where you can easily see what it was but by itself you have no idea of what it was trying to achieve. That these factual changes are so obvious creates a temptation to write very terse commit messages, because in many cases the commit message will just be repeating the change itself. I've come to think that these are among the most important commit messages precisely because they are so disconnected from any higher goal. You can't work out from the change itself whether it's a good or a bad change, so you desperately need to know intentions and context.
(This can't be a new observation and thus I'm sure I'm very late to the party on this one. I've just been thinking about this recently as I made various commit messages at work, sometimes with the feeling that I was being overly detailed in my descriptions (a feeling that I now think is wrong).)