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

Question

I'm curious what kind of content should be in a versioned file commit comment. Should it describe generally what changed (e.g. "The widget screen was changed to display only active widgets") or should it be more specific (e.g. "A new condition was added to the where clause of the fetchWidget query to retrieve only active widgets by default")

How atomic should a single commit be? Just the file containing the updated query in a single commit (e.g. "Updated the widget screen to display only active widgets by default"), or should that and several other changes + interface changes to a screen share the same commit with a more general description like ("Updated the widget screen: A) display only active widgets by default B) added button to toggle showing inactive widgets")

I see subversion commit comments being used very differently and was wondering what others have had success with. Some comments are as brief as "updated files", while others are many paragraphs long, and others are formatted in a way that they can be queried and associated with some external system such as JIRA.

I used to be extremely descriptive of the reason for the change as well as the specific technical changes. Lately I've been scaling back and just giving a general "This is what I changed on this page" kind of comment.

Answer 1

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.

Answer 2

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.

Answer 3

One thing that helps me when thinking about what to write/what not to write, is that eventually it should be possible to compile internal, technical release notes from the commit comments.

I also find it very useful to establish tags in the commit comments, like #doc, #typo, #refactor, ...

I wouldn't be all too descriptive when committing - the reasons for doing something one way or another should be in the documentation, or in the code comments IMO.

Answer 4

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.

Answer 5

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.

Answer 6

If you use a bug tracking system it's best to include the bug / enhancement # you are working on that applies to the change. A lot of times you'll just be re-writing what's in that bug description anyway.

Answer 7

It should contain a small summary of the changes (to allow filtering in a list of changes) and why the change was applied.

The documentation of the new code belongs in the source code itself; not in the log message. (And comments that only applied to the old code should be removed. You can always look at those old comments via the history of your SCC system).