It is fairly well known to most developers that comments should provide value. The following snippet has almost disappeared totally from the codebases I see.
public class Foo {
//Constructor
public Foo() {
//Add one to a
a++;
}
}
The next wave of problems is probably going to be comments elsewhere. Source code repositories like subversion allow comments to be entered during a checkin.
Do you use this feature? If you use it – do your comments provide value, or do they read “checkin”?
I sin against this myself from time to time. Don’t do as I do. I have found that it is very instructive to include my thoughts on what I am attempting to accomplish when I check in. If there is a JIRA (or Bugzilla, RT, Redmine – choose your own poison. Mine is JIRA) issue, I try to remember to enter the issue number.
Then again, people write documents. Most document templates I have used over the years have had a changelog table at the beginning of the document. An example of such a table can be found in my installation guide template. I have now seen some of you use this template, which is why I am writing this post.
The changelog table is there to help the operations team that install the software get a grip on which parts of the document have been updated between versions. If this table does not provide value, the installation document will not be read after the third release, and the installation will break. There will probably be one or more issues registered (“it doesn’t work”, which is an error report that has the same problem I am writing about here), people will get frustrated, and your project will grind to a halt.
Don’t enter comments along the lines of “updated for version 17″ in the description column of this table. Enter something useful. If you rewrote a section, say why and which section(s) was involved. If you have added a configuration parameter, say so, and give a reference to where in the document the parameter is described.
This allows installations to be performed incrementally, which in turn will save money, which in its turn will leave resources for more useful stuff to happen.
Comments can provide lots of value. Make sure you know how to use them wisely.
