Writing Good Check-In Comments

from http://software.jessies.org/scm/

Here’s a checklist of things you should try to get into a habit of going through in your mind as you write a check-in comment:

• Bug/defect number - if you have a bug database, reference it. There’s likely to be plenty of extra information/dialog in there that shouldn’t go to waste. This is why SCM and Edit go out of their way to turn your bug/defect numbers into links.
• Other people involved - if you go under a bus on your way home from work, who else would be worth talking to when it comes to this code? Especially useful if you’re doing something as the result of a request without a formal defect number, or as the result of group consensus.
• Alternatives rejected - we can see what you did implement, but it’s often interesting to know why you didn’t implement other alternatives. Often this is interesting enough to warrant code comments instead. Especially useful if you’re replacing one implementation with another is why the old implementation was no longer suitable.
• Known limitations - these should probably be FIXME or TODO comments in the code.
• Known performance impact - if you measured the performance impact of your change, say so. Mention the tests and the results.
• Evidence to support “premature” optimization - if you’re introducing an optimization, point to a demonstration that it’s useful, or details of the situations in which it’s useful. This will discourage others from backing it out rather than fixing it when it’s demonstrated to be incorrect.
• Text of build errors fixed - if you’re fixing a build error, include the exact error text to help later reviewers determine whether it’s the most appropriate fix or understand your problem so that they don’t re-introduce the build error.