Geek Smithology

October 11, 2005

Why CVS commit messages suck

Filed under: Craft of Dev by Nathan @ 10:36 pm

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

1
latset revision

.

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

1
*** empty log message ***

?

3 Responses to “Why CVS commit messages suck”

  1. Maik says:

    In my company they used to use “*** empty log message ***” an awful lot when I started there. But since I got more and more into sysadmin stuff, I’ve disabled empty messages. Fortunately, my boss didn’t complain at all, and empty messages are still disabled as of today. (In fact, I’ve even disabled messages shorter than 4 characters, not counting whitespace.)

  2. Some guy from your previous employer says:

    This is SO true, there was a time when I used “dev revision” all the time as my CVS commit comment (hey we’re not all BORN perfect.) But since we (read you) installed fisheye and we now have the ability to do all kinds of searching and scanning of our CVS repositories I find useful comments to be invaluable. When we hire a new guy and his first CVS check-in not only doesn’t follow the published CVS commit guidelines, (that you had just instructed him to read prior to making ANY changes in CVS,) but has something like “fixed a bug” in the comments. I can’t help but think something along the lines of: “what is this world coming to??”

  3. Jason says:

    It might be just personal taste, but I also dislike developers that write comment blocks larger than a Victorian novel. One developer I knew would put multiple strings of equal marks between different sections of his comments. This looked fine to him at the time, but it makes all the CVS GUI’s choke. For example, if one did a revision graph on a file that he touched, you would see things such as rev 1.10 coming right after revision 1.2, where did 3 through 9 go? Keep it sweet and to the point.

Leave a Reply

 

Powered by WordPress