About Dalip Mahal

Dalip is a principal consultant at Accelerated Development and has worked his way through all aspects of software development. He started as a software engineer and worked his way through engineering and product management.

Comments are for Losers


If software development is like driving a car then comments are road signs along the way. Comments are purely informational and do NOT affect the final machine code. Imagine how much time you would waste driving in a city where road signs looked like this one. A good comment is one that reduces the development life cycle for the next developer that drives down the road. A bad comment is one that increases the development life cycle for any developer unfortunate enough to have to
 
drive down that road. Sometimes that next unfortunate driver will be you several years later!

Comments do not Necessarily Increase Development Speed

I was in university in 1985 (yup, I’m an old guy) and one of my professors presented a paper (which I have been unable to locate) of a study done in the 1970s. The study took a software program, introduced defects into it, and then asked several teams to find as many defects as they could. The interesting part of the study was that 50% of the teams had the comments completely removed from the source code. The result was that the teams without comments not only found more defects but also found them in less time.

So unfortunately, comments can serve as weapons of mass distraction

Bad comments

A bad comment is one that wastes your time and does not help you to drive your development faster. Let’s go through the categories of really bad comments:
 

  • Too many comments
  • Excessive history comments
  • Emotional and humorous comments

Too many comments are a clear case of where less is more. There are programs with so many comments that it obscures the code. Some of us have worked on programs where there were so many comments you could barely find the code!

History comments can make some sense, but then again isn’t that what the version control comment is for? History comments are questionable when you have to page down multiple times just to get to the beginning of the source code. If anything, history comments should be moved to the bottom of the file so that Ctrl-End actually takes you to the bottom of the modification history.

We have all run across comments that are not relevant.Some comments are purely about the developer’s instantaneous emotional and intellectual state, some are about how clever they are, and some are simply attempts at humor (don’t quit your day job!). Check out some of these gems (more can be found here):
 
 
 

// I am not sure if we need this, but too scared to delete.

//When I wrote this, only God and I understood what I was doing
//Now, God only knows

// I am not responsible of this code.
// They made me write it, against my will.

// I have to find a better job

try {
...
 }
 catch (SQLException ex) {
 // Basically, without saying too much, you're screwed. Royally and totally.
 }
 catch(Exception ex)
 {
 //If you thought you were screwed before, boy have I news for you!!!
 }

// Catching exceptions is for communists

// If you're reading this, that means you have been put in charge of my previous project.
// I am so, so sorry for you. God speed.

// if i ever see this again i'm going to start bringing guns to work

//You are not expected to understand this

Self-Documenting Code instead of Comments

We are practitioners of computer science and not computer art. We apply science to software by checking the functionality we desire (requirements model) against the behavior of the program (machine code model). When observations of the final program disagree with the requirements model we have a defect which leads us to change our machine code model. Of course we don’t alter the machine code model directly (at least most of us); we update the source code which is the last easily modified model. Since comments are not compiled into the machine code there is some logic to making sure that the source code model be self-documenting.  It is the only model that really counts!


Self-documenting code requires that you choose good names for variables, classes, function names, and enumerated types. Self-documenting means that OTHER developers can understand what you have done. Good self-documenting code has the same characteristic of good comments; it decreases the time it takes to do development. Practically, your code is self-documenting when your peers say that it is, not when YOU say that it is. Peer reviewed comments and code is the only way to make sure that code will lead to faster development cycles.

Comments gone Wild

Even if all the comments in a program are good (i.e. reduce development life cycle) they are subject to drift over time. The speed of software development makes it difficult to make sure that comments stay in alignment with the source code. Comments that are allowed to drift become road signs that are no longer relevant to drivers. Good comments go wild when the developer is so focused on getting a release out that he does not stop to maintain comments. Comments have gone wild when they become misaligned with the source code; you have to terminate them. No animals (or comments) were harmed in the writing of this blog.

Commented Code

Code gets commented during a software release as we are experimenting with different designs or to help with debugging. What is really not clear is why code remains commented before the final check-in of a software release.

Over my career as a manager and trainer, I’ve asked developers why they comment their code. The universal answer that I get is “just in case”. Just in case what? At the end of a software release you have already established that you are not going to use your commented code, so why are you dragging it around? People hang on to commented code as if it is a “ Get Out of Jail Free” card, it isn’t.

The reality is that commented code can be a big distraction. When you leave commented code in your source code you are leaving a land mine for the next developer that walks through it. When the pressure is on to get defects fixed developers will uncomment previously commented code to see if it will fix the problem. There is no substitute for understanding the code you are working on – you might get lucky when you reinstate commented code; in all likelihood it will blow up in your face.
 
 

Solutions

If your developers are not  taking (or given) enough time to put in good comments then they should not write ANY comments. You will get more productivity because they will not waste time putting in bad comments that will slow everyone else down. Time spent on writing self-documenting code will help you and your successors reduce development life cycles. It is absolutely false to believe that you do not have time to write self-documenting code. If you are going to take on the hazards of writing comments then they need to be peer reviewed to make sure that OTHER developers understand the code.  Unless the code reviewer(s) understands all the comments the code should not pass inspection.

If you don’t have a code review process then you are only commenting the code for yourself. The key principle when writing comments is Non Nobis Solum (not for ourselves alone). When you run across a comment that sends you on a wild goose chase – fix it or delete it. If you are the new guy on the team and realize that the comments are wasting your time – get rid of them; your development speed will go up.
 
 
 
 
Make no mistake, I am the biggest “Loser” of them all.  I believe that I have made every mistake in the book at least once :-)
 

Reference: Comments are for Losers from our JCG partner Dalip Mahal at the Accelerated Development blog.
Related Whitepaper:

Software Architecture

This guide will introduce you to the world of Software Architecture!

This 162 page guide will cover topics within the field of software architecture including: software architecture as a solution balancing the concerns of different stakeholders, quality assurance, methods to describe and evaluate architectures, the influence of architecture on reuse, and the life cycle of a system and its architecture. This guide concludes with a comparison between the professions of software architect and software engineer.

Get it Now!  

Leave a Reply


seven − = 4



Java Code Geeks and all content copyright © 2010-2014, Exelixis Media Ltd | Terms of Use
All trademarks and registered trademarks appearing on Java Code Geeks are the property of their respective owners.
Java is a trademark or registered trademark of Oracle Corporation in the United States and other countries.
Java Code Geeks is not connected to Oracle Corporation and is not sponsored by Oracle Corporation.

Sign up for our Newsletter

15,153 insiders are already enjoying weekly updates and complimentary whitepapers! Join them now to gain exclusive access to the latest news in the Java world, as well as insights about Android, Scala, Groovy and other related technologies.

As an extra bonus, by joining you will get our brand new e-books, published by Java Code Geeks and their JCG partners for your reading pleasure! Enter your info and stay on top of things,

  • Fresh trends
  • Cases and examples
  • Research and insights
  • Two complimentary e-books