A response to “Comments: A Dissenting Opinion”

4 February, 2011 § 5 Comments

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?

Tagged: , ,

§ 5 Responses to A response to “Comments: A Dissenting Opinion”

  • Adam Richardson says:

    Hi Jared,

    I prefer the “why-comment” version to the version containing the additional function in your examples. I try very hard to get the naming right for my functions, and often a nice function name avoids the need for a “why” comment. However, I’m not going to add another call to the stack JUST for that “why” description, that’s why we have comments (ASP.Net is already slow enough😉 )

    Just happened to check out what you’re up to. Nice, thought-provoking writeup.

    • msujaws says:

      Thanks for stopping by. Yeah I understand the worry about the extra function call on the stack, but most web applications I’ve worked on are not optimized to the point where we could notice delay due to a function call. There is also the high probability that the .net JIT compiler will inline the function so there is no penalty.

  • adam says:

    Hi Jared,

    I was wondering if you checked your comments🙂

    I agree, most web apps wouldn’t notice the delay for A function call. However, when we’re talking about large scale projects, I suspect there are many, many “Why” questions that have to be answered.

    Additionally, I mentioned ASP.Net in my initial post because I know it’s a development environment we’ve both used, but the original post that spawned your response wasn’t ASP.Net specific, and my preference isn’t focused on the ASP.Net development environment (although I certainly do use comments in my current ASP.Net projects.)

    Many projects utilize vast quantities of interpreted code, and answering all of the “Why” questions with additional calls to the stack do add up. I’m thinking of projects like Drupal (PHP), Bugzilla (Perl), RoR (Ruby), and TinyMVC (Javascript, and by the way, not so tiny)?

    Would you maintain your preference working in one of these projects?

    • msujaws says:

      You know I guess it all depends. It depends how rigorous a development team is willing to be. Some teams have glaring performance issues that pale in comparison to 500 extra function calls, while other teams meticulously scrutinize every line of code to make sure they get the best performance.

      With teams that truly prioritize speed, specifically teams that run nightly performance tests or benchmarks, then I would say they might want to look in to seeing what performance gains can be found by removing function calls.

      However, I believe that most teams don’t prioritize speed to that level, and for them the extra function call (if found more useful than a regular text comment) will save them more time in the long run than the penalty of the extra function call.

  • adam says:

    Fair enough🙂

    Happy coding!

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

What’s this?

You are currently reading A response to “Comments: A Dissenting Opinion” at JAWS.

meta