Developer Drain Brain

February 26, 2010

Commit Comments

Filed under: Development — Tags: , , — rcomian @ 9:06 am

There’s been a few blog posts recently about commit comments.

James Lorenzen: http://jlorenzen.blogspot.com/2010/02/commit-comments-conversation-with-your.html

A followup from Kohsuke: http://weblogs.java.net/blog/kohsuke/archive/2010/02/25/what-do-you-try-leave-your-commit-messages

I know that comments can often be treated as one of those horrible tick box enforcements from on-high. However, I’ve eventually come around to a massive appreciation of them, and try to include as much detail as is sensible in my comments. For one thing, it confirms to me that I’ve made a specific change for a specific reason, and not just ‘done some stuff’.

Like eveyone else, I’m curious on how other people view commit comments? Are they unnecessary? (after all, we have diffs). Is just a bugId enough? Should they be short one liners or mini release notes?

Is there scope for bringing commit comments into other parts of the documentation, ie, on the bug reports, release notes, etc.

What, if any, resistance do have to writing a comment when it comes time to checkin?

Advertisements

2 Comments »

  1. I work in open source and detailed commit comments are a necessity.
    We detail to the point of exactly what was altered and why.

    Four reasons for this;
    Firstly it makes sifting through commits looking for a particular change much easier.
    Secondly, it makes regression testing easier and quicker as you can quickly see what changes were made and decide whether that effects your regression area.
    Thirdly, if anyone is reading the diffs, they have a general overview of what the diff is about before they start to read it. This makes the task of reading the diff much more thorougher and also helps to identify if any stray changes were committed in the diff.
    Finally, we use the notes in the commit logs for generate a changelog for each release.

    IMO, commits should be regular and detailed commit logs should be mandatory.

    Ged.

    Comment by Ged Murphy — February 26, 2010 @ 9:19 am

    • If they’re a necessity on open source, is that because of the environment that development happens in? Can you compare that environment to an office – are commit comments necessary there as well? To the same level?

      Certainly I’ve known people who treat commit comments with a certain amout of distain – overhead against getting work done, an annoyance that’s forced on them by others. In a heirarchical, high communication-bandwidth environment like an office, I can see that this attitude might survive where it couldn’t in open source. But is it a justified position?

      Comment by rcomian — February 26, 2010 @ 12:02 pm


RSS feed for comments on this post. TrackBack URI

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Create a free website or blog at WordPress.com.

%d bloggers like this: