My second approach has changed a bit. I still think you're going to have to diff the code to see what really changed. Like I talked about in Code Documentation, meta data is a bad substitute for reading code. However, check in comments can help answer the following questions:
- What did that dude change?
- Which files do I need to diff?
- Could this change be of interest to me?
- If you didn't really change anything, don't leave a comment. If you're checking in a file and all you've done is change the spelling of a variable, or the capitalization of a method, or the wording of a comment, don't bother with the check in comment. No one is ever going to need to diff or read your changes for that version, so save me the time in reading your comment just to figure out that you didn't change anything, and don't leave a comment. If you're required to leave a comment, just put "none" or something equally simple.
- Title what you changed. Pretend you're trying to give the diff between your version and the previous version a Chapter Title. It should summarize the changes you've made at a high level.
- Be as brief as possible. Don't write a book. Don't even use full sentences. How few words can you use to describe the changes you made?
- Group check ins by change. If you're checking in 10 files which have had 5 mutually exclusive changes made to them, don't check them in all at once. Do 5 check ins of two files each. Each check in gets its own comment describing only the changes in those files.
- Check in one change at a time. If you're frequently writing check in comments that say, "Did this and that," could you have done "this" and checked in, then done "that" and checked in?
A check in comment should convey what changed at a high, abstract, level. To figure out how those changes were accomplished: diff. To figure out if those changes might be causing a bug you just found: diff. To figure out how to use the changes: diff. You're better off looking at code to answer those kinds of questions anyway. The check in comment is just a guide to help you figure out where to look.