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 thisSelf-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 :-)
