.NET Zone is brought to you in partnership with:

Mr. Mahal has worked his way through all aspects of software development. He started as a software engineer and learned how to design and architect software systems in different industries. He has been a director of engineering, product management, and professional services; mid-career he worked for a company dedicated to training engineers in collecting requirements and understanding OO and conducted research into why software projects fail; and before starting Accelerated Development he rescued a technology startup in Vancouver as their COO. Accelerated Development is dedicated to the production of high quality software through implementing light weight engineering practices for all size organizations up to Fortune 500. Dalip is a DZone MVB and is not an employee of DZone and has posted 37 posts at DZone. You can read more from them at their website. View Full User Profile

Code Comments are for Losers

06.13.2012
| 21687 views |
  • submit to reddit

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

//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 haveto 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


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.

Other articles

 

References
Published at DZone with permission of Dalip Mahal, author and DZone MVB. (source)

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)

Comments

dieter von holten replied on Wed, 2012/06/13 - 4:12pm

what an irresponsible nonsense...

can you show just one non-trivial 5 year old still alive project which just consists of self-documenting code?

(and of course without any design documents, because 'the code is the design' - as one lunatic said )

i am seriously worried about the idea that there are people not able to write some meaningful sentences but still are expected to write meaningful code..

with this mindset you might write some throw-away prototype for the next exhibition, but not a 'product' which will live and be maintained for the next 5 years.

you might practice this concept for that code you are responsible for - but writing this in a public blog is irresponsible - some folks might believe and do it !!

 

Dalip Mahal replied on Wed, 2012/06/13 - 11:36pm

For some reason half the images are missing.  The first paragraph in particular does not make a lot of sense without the confusing road sign.  I'll see if I can get the good folks at DZone to fix this.  The images are available on the blog.

Tom Blersch replied on Wed, 2012/06/13 - 10:17pm

If comments are akin to road signs for a driver (an apt simile, I believe), then, to stretch the simile to the breaking point, self-documenting code is akin to providing a driver with no signs at all and expecting the route to be taken to simply be self-evident based on the layout of the roads.  (Anyone who believes that's practical, I dare you to drive in Boston.)  

Stretching the simile in the other direction, I've seen standards of "well-commented" code that are akin to providing a road sign every 50 feet.  "You're on Route 311...you're on Route 311...you're on Route 311...you're on Route 311, but will be seeing a light half a mile down the road..."

Basically...this blog article is self-contradictory to the point of nonsense.  The only truly useful content (which I am sharing with my dev team) is the distinction between "good" and "bad" comments.  Everything else written merely distracts from those two statements.

Erik Post replied on Thu, 2012/06/14 - 5:37am

I do my utmost to avoid the need for comments. This usually takes the form of re-reading a comment I added, determining why its there, renaming or restructuring the code a bit and *poof*; the need for the comment is gone. I agree with most of your points, which for me boil down to "make your code self-documenting". I'm therefore a bit surprised at the replies up here.

I do have to say that all of this has been much easier for me in languages that allow me to express whatever it is that I'm trying to model more naturally and, let's not forget, in a much more typesafe way. (Types are a great form of documentation.) In my case, this means Scala and Haskell, where the need for all manner of nebulous incantations and convoluted pattterns that would have required introduction and explanantion is much reduced. Immutability also greatly contributes to the code's comprehensibility, since it removes the need for documenting all kinds of state-related invariants and so on. Certain libraries are especially awful in this respect; some of my old Java code is littered with comments, I'm sorry to say. 

L. E. Kesselman replied on Thu, 2012/06/14 - 7:28am in response to: dieter von holten

Dieter von Holten: Agreed. Yes, there should be design drafts, and supporting materials, neatly numbered, indexed and maintained. Often that doesn't happen. Even brief, but meaningful code comments are valuable, to the original author and to successors. Sometimes I forget why I did something a certain way. Writing a comment makes me think about what I just did, even whether it was a good idea. Unless done compulsively, it need not be a time waste. If others find it cluttered, the comments can be stripped out.

Advising against commenting one's code in a programming education website is irresponsible. Perhaps the republishing by dzone made matters worse, as there were format issues and omissions mentioned by the author (to give benefit of the doubt).

(No one likes to take time to comment code. Lots of reinforcement is required to make it happen. This post is a perfect justification to avoid it. That might not be good.)

Mitch Pronschinske replied on Thu, 2012/06/14 - 8:59am in response to: Dalip Mahal

The first two images are back in. 

Jonathan Fisher replied on Thu, 2012/06/14 - 10:02am

I actually agree with this... I've seen "comments as excuses" way to many times. "Oh hey I wrote some shoddy code... I'll just comment it and it'll be all better." Yah screw that, you wouldn't need to comment the damned code if you just took your time to do it right the first time.

There are some minimum level of comments in my book. First, Interfaces in Java are fully commented, always. A lengthy explanation about expectations about input and output and the result.

Next all classes get a top level description about why they exist and what their scope is. This helps preventing drift out of SRP.

Finally, things that are strange get commented: String.valueOf(myBytes, "UTF-8") produces a checked exception. However, UTF8 is on every friggen system in the world, so it'd be helpful to describe here why this code isn't going to be tested.

Writing small private functions with descriptive names, that do one small thing, not only helps prevent Copy/Pasting, but can help JITmake intelligent decisions about what to optimize. (It also makes the code readable)

All in all, if you're keeping it simple, there's still a minimum level of commenting necessary, but  not every other line and often not inside private methods.

David M. replied on Thu, 2012/06/14 - 11:21am

Too many strawman arguments, a fluff article that has been done too many times.  Make your point about creating support documents and minimizing irrelevant comments and move on.  And since committees don't write code, I'll decide it a comment makes sense, even if it's just for me.

Dapeng Liu replied on Fri, 2012/06/15 - 1:41am

wtb self comment JDK, wtb self comment JEE APIs ... good luck 

Den Fletcher replied on Wed, 2013/06/19 - 5:17am

 An excessive amount of strawman contentions, a cushion article that has been finished an excessive amount of times. Make your focus about making underpin reports and minimizing superfluous remarks and proceed onward. At Fetele Norocoase , since trustees don't compose code, I'll choose it a remark bodes well, regardless of the possibility that its just for me.

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.