Posted by kohsuke
on February 25, 2010 at 10:09 AM PST
James Lorenzen had an excellent blog post about the importance of a descriptive commit comment. I can't agree more, so I listed up what I try to leave in the commit messages. What do you try to leave in your commit messages?
James Lorenzen had an excellent blog post about the importance of a descriptive commit comment . I can't agree more.
Unfortunately, I think getting better at leaving better commit messages take trial and error — the way I've learned it is by getting frustrated by the lack of commit messages. So in the spirit of encouraging everyone (including myself) to do a better job, I thought I'd list up what I try to leave in the comments.
- Bug ID. In fact, bug/commit association is so useful that often you use (or write) programs that analyze these relationship, so it's preferrable for this information to be machine readable.
- URL to the e-mail in the archive that prompted me to produce a change. In Hudson, often a conversation with users reveal an issue or an enhancement that results in a commit. This URL lets me retrieve the context of that change, and I find it tremendously useful.
- If the discussion of a change was in IM, not e-mail, I just paste the whole conversation log, as they don't have an URL. Ditto if the e-mail was sent to me privately.
- The input value and/or the environment that caused a misbehavior. In Hudson, I have this one method that needs to do some special casing for various application servers. When I later generalized it a bit more, commit messages that recorded the weird inputs from WebSphere, OC4J, and etc. turned out to be very useful.
- For a fix, a stack trace that indicates the failure. Sometimes I misdiagnose the problem, and later when I suspect I did, being able to see the original output really helps me.
- If I tried/considered some other approaches to the problem and abandoned them, record those and why. I sometimes look back my old change and go "why did I fix it this way — doing it that way would be a whole lot better!", only to discover later that "ah, because this won't work if I've done that!", and I knew I've gone through the same trail of thoughts before. If I'm in a middle of a big change and decide to abandon a considerable portion of it, I sometimes even commit that and roll it back, just so that I can revisit why I abandoned it later.
- If a change should have been logically a part of a previous change, just say so. If I happen to know the commit ID of the previous change, I definitely leave that, but if I don't remember it, I still try to point to where that previous change was, like roughly when it was made, which file it was made, who did it, etc, so that future myself can narrow down the search space if I need to find it.
What do you try to leave in your commit messages?