You envisioned the perfect feature. You designed it with an astounding mix of elegance and innovation, and implemented it so cleanly, with illuminating comments and not a single superfluous line of code. Overwhelmed, you print the code just to admire its beauty.
Then you check it into CVS with a commit message of
I understand the fact that many developers (some would say most, but that’s too scary for me to even contemplate) don’t use version control, by why do the ones that do write such crappy commit comments? It’s because they see it as a convenient place to put code, not as the invaluable resource it should be.
Next time you commit, don’t think of the comment as an annoying popup you have to dismiss as quickly as possible; think of how you would describe your change in the release notes for your next production build.
“But you can just get a diff”, you say? That’s naive and perhaps even ignorant. You know how comments in code should help give an overview, maybe explain the why instead of the how? Your CVS comments should act the same way – I should be able to browse the changelogs in FishEye and get an overview of what’s been going on. If I want some detail, I can drop in and check out a diff, but that should be at my discretion, not yours.
Commit messages are your chance to tell the world what you were thinking at the time you wrote your code. Are you sure you want to say
*** empty log message ***