What information should a SVN/Versioned file commit comment contain?

Useful commit comments are those that add useful information that isn't easily extracted from the changes themselves. Looking at the diffs will show what changed, so the commit comment should concentrate on explaining WHY the changes were made:

  • Fixed crash due to NULL pointer dereference (bug ID 234).

  • Added command to disconnect from server (feature request 22).

  • Cleaned up code for future changes.

Another useful sort of comment is one that summarizes the overall purpose of a larger set of changes:

  • Added support for allowing user to frobulate the widget.

Some guidelines:

  • don't write stuff that the VC system already tracks automatically: which files, how many lines, when, who did the change...
  • do write what the purpose of the change was: "add UTF-8 support to ID3 tags"
  • if you find that the purpose is unclear or multiple, you are probably better off doing several commits instead. Linus Torvalds can get away with writing "various fixes all over the place"; the rest of us shouldn't take him as an example.
  • if you have any sort of tracking system that assigns unique identifiers to issues or feature requests, by all means tag the comment with that identifier.

Personally, I try to make a brief summary of what I changed and/or added. Something that will remind me, "Oh yeah, this is [probably] where I added that extra rule to the business object." Because I can always run a "diff" to see specifically what changed.


it should briefly explain what the commit contains. This should include a ticket number for a bug fix or enhancement. The best advice I have ever heard about writing comments is this "Code as if the next guy to maintain your code is a homicidal maniac who knows where you live" This is equally appropriate to commit comments.