We're looking for long answers that provide some explanation and context. Don't just give a one-line answer; explain why your answer is right, ideally with citations. Answers that don't include explanations may be removed.

11 Answers
11

If you are not using a bug tracker, and as such, cannot include a bug report id/number, you have to be very descriptive in your comments. Otherwise, if you just write "fixed problem with X" for example, two weeks after the commit you won't remember what was the problem. In that case, you will need to compare the before and after commit versions to understand what it was.

When I started developing applications professionally, we did not use a bug tracker, and I can remember that sometimes comments were very descriptive (too much even), sometimes there was no comment at all, it was a mess. With a bug tracker id, comments are way more useful and with a few more words you may even indicate why you made that particular change. Also, IDE's such as Eclipse for example have plugins that detect the bug tracker id's in comments (and in source code also) and can provide a clickable link to the bug tracker's web page.

Commit comments are about seeing easily what was changed. They are there for your reference, so how much detail that you put in them will depend on how much effort you want to spend now to save you time in the future. Generally speaking, a little effort at commit time has the potential to save a lot of time in the future.

For instance, say to changed a <= to a > and a ++ to a -- in a loop, but didn't add a descriptive commit comment. Later, it would be difficult to find the revision where you reversed the direction of the iteration. If you'd commented "Reversed direction of blah index traversal" then it would be much easier to find that revision by searching the revision log.

This is why including issue tracking information in commit messages is a really good idea. Say you fix a bug, then later the issue is re-opened because it wasn't completely fixed. If your commit comment of the original fix mentioned the issue tracker identifier, you can easily find it and later still you can easily find all revisions associated with that issue.

I tend to write a concise form of what I'm committing; if it's for a specific task, I'll include the task number in the message. Things like:

Changed foobar module to account for the new baz; created quux pages and data objects.

What not to do is write some nonsense like "Oops" or "Added comments" (both of which I have seen added in the commit logs by a co-worker), or worst of all do something like I saw the other day - A single file was checked in, with the commit message "Comment" (exact quote). What was added, you may ask? Something to the effect of:

I think that this all boils down to how you manage your projects. For me, I tend to commit whenever I finish a feature that I want to push to a release build. Since in my case, every feature results in a commit, I use my feature's story and issue number as my comment. The same goes for fixing bugs. I start with a spike, derive a story, use the story to describe the changes that I need to make, and once again commit to source control with a story in the comments.

Most issue trackers have a format that they can parse issue IDs out of commit messages and group commits with issues.

If you don't use an issue tracker, you should, it doesn't matter you are a solo developer, I've elaborated on the matter on another answer:

Use an issue tracker. It doesn't matter you are a lone wolf, keep track of everything you do for your project, whether it's a feature or a bug. Make a feature / components list. Mark truly essential components as version 1.0 and all else as version 2.0. And then delete everything that's marked as 2.0.

Ok, since the question got a mod notification for longer answers, I feel obliged to expand:

Yes, I just put the issue ID in commit comments, nothing else. That's when on solo projects, on team projects it's a whole other story. I'm not advocating putting just the issue ID, there should be something more there, but:

On solo projects it's extremely tempting to not document anything,

Putting the issue ID means by default that you've gone through the process of setting up an issue tracker,

That's good enough for me.

Effectively using an issue tracker when developing solo it's a far bigger achievement than commit comments. It'd be nice if I had the motivation to add something helpful in the comments, but I don't.

I generally put the purpose of the check-in at the top. This may be the name of a feature request, ticket number, etc.

I then follow it up with the list of the files affected and the specific changes required in each file. This is particularly helpful when one is looking at the revision history of a file as opposed to the project/folder.

The changes that you have made to the code and what ever else that might be of relevance including put not limited to bug fixes, new features, breaks in functionality, changes in libraries, etc. Of course since the code is committed in small increments it will not have all the above. E.g. if you are fixing a bug you might make multiple changes. This will be multiple commits to fix the bug but what changes you made to fix the particular bug.

The most important bit of information in the commit log is the 'why', not the 'what'.

A short summary of the changes can be useful, but usually you can get that information from the diff itself. It's not a huge problem if that's missing.

Looking back at a commit log, you'll want to know why that change was done. A bug ID can go a long way in answering that question. Sometimes more explanations are required.
For example, if you fix a probem on bad input explain what input caused the problem, and if it's not trivial also how it could occur.