Everyone knows that source control is fundamental to the practice of modern software development, but most people don’t know how to use it. Today I want briefly comment on comments.
Comments with your commits are important; I assumed this was obvious, why should you comment your commits? Comments quickly tell you: what changed, why it changed, which files you will need to Diff and if change is of interest to you. If your developers use good commit comments, then your repository will not only contain every change you have ever made, it’ll also have an explanation of all those changes. As a project develops and matures, these kinds of comments are invaluable, especially when you consider developer turnover.
If you don’t comment your commits, then the only information you have is that Joe committed a file in March. Now you’ll spend 30 minutes figuring out what changes he made; if you’re lucky Joe’s still around and he still remembers why he made those changes–tracking down Joe, that’s another 30 minutes. In all likelihood, Joe doesn’t remember why he made those changes, and without comments there’s nothing to cue his memory, but you really need to know why he made this change, so you insists that he checks his emails from March, maybe something in his email will jog his memory.
Yes, you’ve just wasted 2 hours of development time because you didn’t comment your commits.
Related posts:
Very nice Shey.
I also like to comment my commit, whenever I commit my code to the source control. It not only helps others who are working on the same project, but it also helps me when I checkout the code after sometime, by looking at the commit comments I could see why I did this and that.
Meraj Rasool - 2 Jun 08 at 10:02 am
You’re exactly right, it’s not only for other developers, it’s for yourself as well.
sheys - 2 Jun 08 at 10:23 am
We comment our commits and include a link to the bug/change link from Trac. What would be kind of cool is have a code inspection tool inside Visual Studio where you can hover over an area, click a few buttons and magically retrieve comments on previous commits of the section of code you’re looking at…maybe VisualSVN has it, need to check it out.
Tom - 2 Jun 08 at 6:46 pm
Tom,
That would be a very nice feature to have; it wouldn’t be too hard to implement either if you’re bug tracking software provided a RESTful interface.
TFS has some very cool features that I wish AnkhSVN supported.
http://www.codinghorror.com/blog/archives/000992.html
Shey - 2 Jun 08 at 11:15 pm
A few comment-less commits are okay if you’re just continuing a previous commit, but when someone else is going over the logs, it’s really nice to see what each commit was doing.
It can also REALLY help with tracing bug tickets and collecting information for release notes.
Ben Scheirman - 2 Jun 08 at 11:30 pm