SCM is a cross-platform GPL front-end to revision control systems, able to work with Bazaar, BitKeeper, CVS, Mercurial, and Subversion repositories.
SCM is currently unavailable. This is to ensure our compliance with new restrictions in the BitKeeper 4 license. SCM will not return until six months after the last of us stops using BitKeeper.
We're sorry for the inconvenience. In the meantime, our guide to writing good check-in comments remains in its original form below...
When you start CheckInTool, it will tell you what to do next. The idea is that you check a file you want to commit, then type the comment corresponding to that file, then repeat for all the other files you want to include in the change set.
It turns out to often be convenient to group files. Rather than repeating a comment, just group the affected files together. The GNU style allows you to repeat a filename if you have more than one thing to say about it, but SCM doesn't really help you with that: you'll have to copy and paste the name yourself. Another common practice is to show related sub-changes and their relation by writing ellipses between chunks of the story.
Here's an example of the kind of comment SCM will naturally help you write:
src/e/scm/WaitCursor.java: making this a class full of static data and methods was stupid. To cope with nested tasks, change it to something you instantiate... src/e/scm/BlockingWorker.java: src/e/scm/PatchView.java: src/e/scm/RevisionWindow.java: ...and change all the callers.
You can write anything you like, of course, but you'll get less help.
The text area is 80 columns wide, but the text is only soft-wrapped. If you want line breaks, you'll have to type them yourself. Anywhere SCM shows you a comment, it will word-wrap for you, so hard line breaks shouldn't be necessary.
BitKeeper supports giving a different comment to each file in a change set, and yet another comment to the set as a whole. SCM doesn't support this. One reason is that other back ends don't. But more than that, experience suggests that this freedom isn't useful, and does cause problems. One common case is that people accidentally hide important details by pasting the same comment for most of the files, but editing one or more of the copies. This is very easily missed when you're reading the history. Another common case is where important detail is hidden in the change set comment, which isn't visible when you're looking at one file's history. In all cases, it's unnecessarily awkward to see the commentary on the change set as a whole. You could argue that this is a weakness of the tools, but I think it's a weakness of the idea itself. The dialog style of commenting works better, and fits the idea of a change set as a coherent group of changes.
In effect, SCM forces you to write only a change set comment, which it then applies to each file, and to the change set.
One reason check-in comments are useful is, as Chris Aston always says, it's a safe assumption that "I'm not cleverer today than I was yesterday". So if you see something that's wrong, or weird, it's worth trying to find out where it came from. And that's when you're dealing with your own code! It's even more important to do a bit of archaeology if you're working on someone else's code.
This helps guide us in writing good check-in comments. As you write, imagine someone who's left the company has already written the comment, and you're only reading it. Think about what you'd most like to see.
I explained above why you should comment the "change set", naming all the files touched, and the relationship between the individual files' changes.
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.
I won't insult you by reminding you that saying what you've done is never as useful as why you did it, though such comments can be useful if you accidentally add/change/remove code you didn't mean to touch. If it's not mentioned in the check-in comment, that lends credence to the belief that it was a mistake.
I also won't insult you by reminding you that duplication is bad in comments as well as code. Don't repeat yourself (except in mentioning bug/defect numbers, which should always appear in the check-in comment, and should often appear in the source too), and favor commenting the source. The main reason for commenting a check-in is that it's often the only way to express the commonality between changes made to different files. This is another reason to favor the "change set" style of commenting: someone looking at any file can trivially see the context of the change.
One final tip: the more likely it is that someone will need a piece of information to understand the code, the stronger the pressure to include that information in a code comment rather than a check-in comment.