Best practices for version control comments

Question

There is a lot of conversation about commenting code, but how about commenting on check-ins?

I found this blog post: http://www.redbitbluebit.com/post/Subversion-Check-In-Comment---Great-Practices.aspx

As the guy who is putting together the release notes, I am looking for ways to make that job easier.

Currently we defined our own scheme with <Begin_Doc>...<End_Doc> for anything that should be published to our software customers. But even for the internal stuff, I'd like to know the "why" for every change.

Answer 1

Every feature has a ticket/issue/bugreport/task/whatever-you-call-it, and the ticket number is always referenced in the check-in comment. This gives context.

Answer 2

I would advocate NOT using/overloading your version control system for this. I would suggest the issue tracking software as a better fit.

For one, it does not seem appropriate to have developers add all the context and duplicated information in a commit message that is already in a requirements doc or issue/defect system.

You can use a tool to gather the relevant fixes/issue numbers that are in the commit comments and then go collect those from your other repository, but I think it is a mistake to basically make your revision tool an external facing thing.

You need to define what the Source/version repository/SVN is - is it for managing your source files, or is it also for writing release note. I think it should not be overloaded.

Answer 3

The key is what are you going to do with the comments. If you're creating release notes, then you can do as you suggested. However I would recommend instead you keep track of release notes somewhere else, such as in a project management or bug tracking tool.

As for developer related comments, we've generally asked people to explain what they're doing, a one sentence explanation. It doesn't need to be too formal, mainly because if it is people will push back against it. Plus, if you know who did it, and you have a quick comment, you can generally trace back the issue and find the person.

As well, if you use a tool like FogBugz, you can link an SVN checkin to a case number. Which means that you can look up the case to get the full discussion, comments, screenshots, etc. Which is much more information than you could ever enter in a checkin comment.

Answer 4

I would say to try to follow a changelog style. The first line should be a short summary, and include the issue/ticket number (if any). This should possibly be followed by a blank line depending on how your VCS handles multi-line commit messages, then a fuller multiline description. I would say it's unreasonable to impose any strict formatting since it will discourage frequent commits, but so long as the important commits (the ones closing issues, or major changes) are done this way you should be ok.

If you use something like Trac or roundup + svn integration, it can pick out issue numbers from the commit messages. I would always put these in the first line since they're so useful.

Answer 5

Agree with Remembrance, but you should also write a little bit about why you implemented the change /bug fix the way you did. If you belive in checking in often, you should also include TO DO's in order to make it possible for one of your co-workers to complete the task.

Answer 6

I subscribe to DRY here as in all things.

I almost never add a comment to my commits. A comment is almost always repeating myself. The answer to the question "what changed in this commit"? is almost always in the diff.

When I'm looking at a file and I ask "what the hell happened here?", the first thing I do is look at the diff with the previous rev. 90% of the time the answer is immediately apparent, either because the code's self-evident or because there was something not self-evident that I commented in the code. If it's not, I correlate the rev dates of the file with the bug-tracking system and the answer is there.

This always works. It sometimes requires a little investigation to figure something out, because I didn't comment my code adequately. But I've never been unable to find the answer fairly quickly.

The only time I add a comment to the commit log is when I know that a diff isn't going to help me. For instance, when I sort a class's members: the only thing that a diff is going to tell me in that case is that something very big happened. When I do that, I commit the file as soon as I've fixed it. There's no appropriate place to comment a change of that scope in the file, so I add a comment to the effect that the only change in this rev is reordering the members.

("Why wouldn't you comment a change like that in the revision history at the top of the file?" you might ask. I don't keep a revision history at the top of my files. That was a scary, break-the-habit-of-a-lifetime change to make, and I've never regretted it for a moment. The revision history is Subversion.)

If I didn't have 100% ownership of the project, it might be different. It might be too hard to correlate commits with bug fixes. It might be too hard to train other developers to code to a style that makes it possible to rely on version control effectively. I'd have to see.

Answer 7

I recommend functional comments. The comments should give a summary of what was changed. If something was changed, and why. Every commit should be explainable, if you can't explain it clearly, you probably shouldn't be checking it in.

The most important thing to remember when using source control logs is they are there to determine when and what was changed. The more functional, and detailed the better. commits should be made in bite size pieces, that can be explained with bite size comments.

My personal preference is this style:

UPDATED the error logging system.

1. Added a legacy error parsing routine using regex to get the legacy error codes.
2. Changed the text in the database error messages, to correct misspellings.
3. Removed commented out sections of code, because they were not used any more.

Answer 8

Making my changes small helps: I can provide detailed descriptions of my changes this way.

The checkin comments should be the information that a developer wants: this includes refactorings, motivation behind the code, etc.

Answer 9

We try to keep it simple: write one sentence describing the change that you are committing. If a developer needs two or more sentences to describe the commit, then perhaps the commit is two unrelated pieces of work. When commits like this end up in version control, then it is difficult to revert fixes in isolation.

Another piece of information that we like to include in our commit comment is the defect / feature number that the commit fixes / implements. Not all work that we do is related to a defect in our issue tracking system, so this is not compulsory.

One last piece of information that we put in our commit comments is the name of one code reviewer. This is the person who did a sanity check on the changes before the commit takes place.

Answer 10

On our projects we always advocate providing some detail to what a commit is about and to assist in not having to duplicate information like the problem we use Trac and have our repository integrated. The advantage is that you can then reference the issue ticket in the comment and only state the resolution or steps of work carried out. Trac then automatically links the reference number to the original issue number and applies your commit message as a comment to the issue. Then when you want to see what has been done you can simply read the issues within Trac and have full context.

With regards to release notes we have found that taking the list of issues within a release and using the commit information as a basis for the comments has worked fine. Generally you will not have release notes that have the raw commit messages in them as your clients do not really care about every little change or even the level of detail that may be included in the comment. So you would normally need to do a fair amount of editing to highlight the main changes and bug fixes implemented in that release.