A response to “Comments: A Dissenting Opinion”

This past Thursday, our second post of the new Dev Corner was published and featured thoughts on code comments from Matt Mercieca.

The post is really well written and generated a lot of conversations within our internal development blog at TechSmith. Code comments are one of my bike-shed problems (I prefer green by the way), but I do feel inclined to respond.

Much of the post pits “how-comments” versus “why-comments”. I believe that it is well understood that “how-comments” are little cared for. For example, the comment in the following code offers no value to the reader:

//print out array
for(var i in objects) {
  document.write(objects[i]);
}

However, the “why-comments” is where the real discussion is. Respectfully, I stand on a different side of the fence when it comes to “why-comments”. I believe that what can be written as a comment can also be written as a function or variable name. Consider the following two code samples:

var printOrders1 = function()  {
  // this query is a hack due to weird SQL Server Query Optimizer bug
  var orders = sqlConnection.execute('SELECT TOP 1000 FROM tblOrders WHERE ...');
  print(orders);
};

var printOrders2 = function()  {
  var executeQueryForOrdersWithHackForQueryOptimizer = function () {
    return sqlConnection.execute('SELECT TOP 1000 FROM tblOrders WHERE ...');
  };
  var orders = executeQueryForOrdersWithHackForQueryOptimizer();
  print(orders);
}

I feel that the second version contains the same information as the first version, but will be read more often. As code gets duplicated (unfortunately), sometimes comments get stripped. It is less likely that a function like this will get renamed to a more innocent name.

Where do you stand?