Shey’s Rebellion

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.

This entry was posted on Saturday, May 31st, 2008 at 12:36 pm and is filed under programming. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.