Software Engineering Stack Exchange is a question and answer site for professionals, academics, and students working within the systems development life cycle. It only takes a minute to sign up.
Sign up to join this community
I am a lone developer and maintain a SVN server for source control. So far, I haven't followed anything specific while committing my changes.
I was just reviewing my previous commits, and couldn't make any sense of my comments.
What do you put in comments while committing your checkins?
You might be interested in reading this: https://stackoverflow.com/questions/321720/best-practices-for-version-control-comments.
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.
What did you expect to find in the comments of your previous commits?
Just put that information in your next commits.
Sometimes a ticket ID is enough, a ticket representing a bug report or a feature request.
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:
if (z == true) {
x = y; // x is being overridden here... <--- added in commit
}
And no, we are not measured by the number of commits.
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.
Issue ID.
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:
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.
Something like
Ticket 101 fix web service exception when uploading widget
Bug was caused by users uploading incomplete widgets (widgets without wonkers)
webservice.cs:
improved post validation for incomplete widgets
added default exception handler to ProcessWidget
widget.cs: handled the SqlException when inserting widgets without wonkers
Generally, what you worked on in that commit is a good start :)
(out of curiousity... what have you been writing if you couldn't make any sense of it?)
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.
We are using assembla on our project. We build the cardwall with all featuers/bugs that need to be done and when commiting we just refer to this ticket
For example:
see #243
- Grid listed all users with an income more then 1000$ but not the ones that have
exactly 1000. Added a >= in the file xy.cs on the line xyz
This way you we are able to pinpoint the changes quicker and find some mistakes easier
