John Fuex has been working in software development professionally for over 15 years in Austin, Texas. Although he still keeps his hands dirty in code as much as possible, he has spent most of the last decade managing software development teams for a litigation services company. His passions are software development process improvement and mentoring aspiring novice programmers. John is a DZone MVB and is not an employee of DZone and has posted 5 posts at DZone. You can read more from them at their website. View Full User Profile

5 Best Practices for Commenting Your Code

07.08.2011
| 19463 views |
  • submit to reddit

One of the first things you learn to do incorrectly as a programmer is commenting your code. My experience with student and recently graduated programmers tells me that college is a really good place to learn really bad code commenting techniques. This is just one of those areas where in-theory and in-practice don’t align well.

There are two factors working against you learning good commenting technique in college.

  1.  Unlike the real world, you do a lot of small one-off projects as a solo developer.  There’s no one out there fantasizing about dropping a boulder on you for making them decipher your coding atrocity.
  2.  That commenting style you are emulating from your textbook is only a good practice when the comments are intended for a student learning to program. It is downright annoying to professional programmers.

These tips are primarily intended for upstart programmers who are transitioning into the real world of programming, and hopefully will prevent a few from looking quite so n00bish during their first code review. Code Review? Oh yeah, that’s something else they didn’t teach you in school, but that’s a whole other article, I’ll defer to Jason Cohen on that one.

So let’s get started…

(1) Comments are not subtitles

It’s easy to project your own worldview that code is a foreign language understood only by computers, and that you are doing the reader a service by explaining what each line does in some form of human language. Or perhaps you are doing it for the benefit of that non-programmer manager who will certainly want to read your code (Spoiler: He won’t).

Look, in the not too distant future, you will be able to read code almost as easily as your native language, and everyone else who will even glance at it almost certainly already can. By then you will realize how silly it is to write comments like these:

// Loop through all bananas in the bunch
foreach(banana b in bunch) {
    monkey.eat(b);  //make the monkey eat one banana
}

You may have been taught to program by first writing  pseudo-code comments then writing the real code into that wire-frame. This is a perfectly reasonable approach for a novice programmer. Just be sure to replace the comments with the code, and don’t leave them in there.

Computer: Enemy is matching velocity.
Gwen DeMarco: The enemy is matching velocity!
Sir Alexander Dane: We heard it the first time!
Gwen DeMarco: Gosh, I’m doing it. I’m repeating the darn computer!

-Galaxy Quest

Exceptions:

  • Code examples used to teach a concept or new programming language.
  • Programming languages that aren’t remotely human readable (Assembly, Perl)

(2) Comments are not an art project

This is a bad habit propagated by code samples in programing books and open source copyright notices that are desperate to make you pay attention to them.

/*
   _     _      _     _      _     _      _     _      _     _      _     _
  (c).-.(c)    (c).-.(c)    (c).-.(c)    (c).-.(c)    (c).-.(c)    (c).-.(c)
   / ._. \      / ._. \      / ._. \      / ._. \      / ._. \      / ._. \
 __\( Y )/__  __\( Y )/__  __\( Y )/__  __\( Y )/__  __\( Y )/__  __\( Y )/__
(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)
   || M ||      || O ||      || N ||      || K ||      || E ||      || Y ||
 _.' `-' '._  _.' `-' '._  _.' `-' '._  _.' `-' '._  _.' `-' '._  _.' `-' '._
(.-./`-'\.-.)(.-./`-'\.-.)(.-./`-'\.-.)(.-./`-'\.-.)(.-./`-'\.-.)(.-./`-'\.-.)
 `-'     `-'  `-'     `-'  `-'     `-'  `-'     `-'  `-'     `-'  `-'     `-'

                 -It's Monkey Business Time! (Version 1.5)
*/

Why, that’s silly. You’d never do something so silly in your comments.

ORLY? Does this look familiar?

+------------------------------------------------------------+
 | Module Name: classMonkey                                  |
 | Module Purpose: emulate a monkey                          |
 | Inputs: Bananas                                           |
 | Outputs: Grunts                                           |
 | Throws: Poop                                              |
+------------------------------------------------------------+

Programmers love to go “touch up” their code to make it look good when their brain hurts and they want something easy to do for a while. It may be a waste of time, but at least they are wasting it during periods where they wouldn’t be productive anyway.

The trouble is that it creates a time-wasting maintenance tax imposed on anyone working with the code in the future just to keep the pretty little box intact when the text ruins the symmetry of it. Even programmers who hate these header blocks tend to take the time to maintain them because they like consistency and every other method in the project has one.

How much is it bugging you that the right border on that block is misaligned? Yeah. That’s the point.

(3) Header Blocks: Nuisance or Menace?

This one is going to be controversial, but I’m holding my ground. I don’t like blocks of header comments at the top of every file, method or class.

Not in a boat, not with a goat.
Why? Well let me tell you, George McFly…

They are enablers for badly named objects/methods – Of course, header blocks aren’t the cause for badly named identifiers, but they are an easy excuse to not  put in the work to come up with meaningful names, an often deceptively difficult task. It provides too much slack to just assume the consumer can just read the “inline documentation” to solve the mystery of what the DoTheMonkeyThing method is all about.

JohnFx’s Commandment:
The consumer of thy code should never have to see its source code to use it, not even the comments.

They never get updated: We all know that methods are supposed to remain short and sweet, but real life gets in the way and before you know it you have a 4K line class and the header block is scrolled off of the screen in the IDE 83% of the time. Out of sight, out of mind, never updated.

The bad news is that they are usually out of date. The good news is that people rarely read them so the opportunity for confusion is mitigated somewhat. Either way, why waste your time on something that is more likely to hurt than help?

JohnFx’s Maxim of Plagiarized Ideas :
Bad Documentation is worse than no documentation.

Exception: Some languages (Java/C#) have tools that can digest specially formatted header block comments into documentation or Intellisense/Autocomplete hints. Still, remember rule (2) and stick to the minimum required by the tool and draw the line at creating any form of ASCII art.

(4) Comments are not source control

This issue is so common that I have to assume that programmers (a) don’t know how to use source control; or  (b) don’t trust it.

Archetype 1: “The Historian”
// method name: pityTheFoo (included for the sake of redundancy)
// created: Feb 18, 2009 11:33PM
// Author: Bob
// Revisions: Sue (2/19/2009) - Lengthened monkey's arms
//            Bob (2/20/2009) - Solved drooling issue
	 
	void pityTheFoo() {
     ...
}

The programmers involved in the evolution of this method probably checked this code into a source control system designed to track the change history of every file, but decided to clutter up the code anyway. These same programmers more than likely always leave the Check-In Comments box empty on their commits.

I think I hate this type of comment worst of all, because it imposes a duty on other programmers to keep up the tradition of duplicating effort and wasting time maintaining this chaff. I almost always delete this mess from any code I touch without an ounce of guilt. I encourage you to do the same.

Archetype 2: “The Code Hoarder”
void monkeyShines() {
    if (monkeysOnBed(Jumping).count > max) {
        monkeysOnBed.breakHead();
 
	        // code removed, smoothie shop closed.
	        // leaving it in case a new one opens.
	        // monkeysOnBed.Drink(BananaSmoothie);
   }
	}

Another feature of any tool that has any right to call itself a SCM is the ability to recover old versions of code, including the parts you removed. If you want to be triple super extra sure, create a branch to help you with your trust issues.

(5) Comments are a code smell

Comments are little signposts in your code explaining it to future archaeologists that desperately need to understand how 21st century man sorted lists of purchase orders.

Unfortunately, as Donald Norman explained so brilliantly in The Design of Everyday Things, things generally need signs because their affordances have failed. In plain English, when you add a comment you are admitting that you have written code that doesn’t communicate its purpose well.

Sign:"This is a mop sink." Why would that be necces... oh.

Despite what your prof told you in college, a high comment to code ratio is not a good thing.  I’m not saying to avoid them completely, but if you have a 1-1 or even a 5-1 ratio of LOC to comments, you are probably overdoing it. The need for excessive comments is a good indicator that your code needs refactoring.

Whenever you think, “This code needs a comment” follow that thought with, “How could I modify the code so its purpose is obvious?”
Talk with your code, not your comments.

Technique 1: Use meaningful identifiers and constants (even if they are single use)

// Before
 // Calculate monkey's arm length
 // using it's height and the magic monkey arm ratio
 double length = h * 1.845; //magic numbers are EVIL!
	 
// After - No comment required
double armLength = height * MONKEY_ARM_HEIGHT_RATIO;

Technique 2: Use strongly typed input and output parameters

// Before
	 
 // Begin: flip the "hairy" bit on monkeys
	 foreach(monkey m in theseMonkeys) {
	     // 5-6 steps to flip bit.
	 }
 // End: flip the "hairy" bit on monkeys
	 
// After No comment required
flipHairyBit(theseMonkeys);

As an added bonus, technique 3 will tend to reduce the size of your methods and minimizing the nesting depth (see also “Flattening Arrow Code”) all of which contribute to eliminating the need for commenting the closing tags of blocks like this:

     } // ... if see evil
    } // .. . while monkey do.
   } // ... if monkey see.
  } // ... class monkey
} // ... namespace primate

Acknowledgments

Several of the ideas presented here, and a good deal of the fundamental things I know about programming as part of a team, and not as a lone-wolf working on a college project I learned from the book Code Complete by Steve McConnell. If you are a working programmer and have not read this book year, stop what you are doing and read it before you write another line of code.

 

 

From  http://improvingsoftware.com/2011/06/27/5-best-practices-for-commenting-your-code/

Published at DZone with permission of John Fuex, author and DZone MVB.

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

Comments

Erwin Mueller replied on Sat, 2011/07/09 - 8:09am

The last point is a very important one. Why do programmers comment block of code, if there is already a language feature for that: a method (or function)? A method name is just a block comment, and we are way over the good-old-days where function names could only have 8 characters. Modern languages support even Unicode now, and more modern languages can have a String as a method name, like in Groovy:

def "flip the 'hairy' bit on monkeys"() {
}

 

Lund Wolfe replied on Sat, 2011/07/09 - 1:58pm

I did really appreciate "Code Complete" but maybe I didn't agree with everything, or under every circumstance.

I believe in /* */ comments above methods when they are useful. I don't need a formal header comment listing every argument, etc. In reality, most code is not well written, so I'll take comments rather than nothing at all to help me understand the code. I also practice and appreciate code with "Historian" and "The Code Hoarder" comments. If I'm doing my own new development, which reads like a children's story then I don't need such clutter and few comments. In reality, though, I am often doing maintenance on code where the domain is in flux or not well understand, the code is brittle, or the previous programmers have not made good judgement calls in new development or maintenance. At a minimum I'd like to see a bug # and date, but it would be nice to see the old code in comments (if only a few lines long) and thoughts on the why for the change. I could check the changeset and read the overall changeset comments every time, but I'd rather see it just by looking at my latest source files and search on the related changes by bug # or date. If changes are being made in the same section indicating a code quality or requirements stability problem, I'd like to see it in the code rather than making the change as if it was the first time every time.

I have been the victim of comments being stripped out of the code indiscriminately. That scares me more than having some bad/outdated/misleading comments in the code.

Mohan Ambalavanan replied on Sun, 2011/07/10 - 7:33pm

Excellent article!! Though most of us (Senior Developers) would have learn't from Books,on daily basis, I have seen all the above in  our codebase. 

Praveena Manvi replied on Mon, 2011/07/11 - 1:48am

Well written, agree with all points. The rule "it should not be cryptic or verbose" is same for documentation and code. What's your take on practices with JavaDoc comments (private methods, get/set methods)

Sakdsitt Likhit... replied on Mon, 2011/07/11 - 4:30am

Excellent article!!

Michael Gower replied on Tue, 2012/04/17 - 2:13pm

Fantastic article.  However it didn't mention anything about how to use comments to chunk a class into various sections.  I made a post on this related topic at my blog, Hacker's Valhalla.

Again, great article, easy to pick out the main points, thank you.

Roman Ivanov replied on Sun, 2014/02/09 - 8:58pm

Checkstyle  project is considering to add support for Comments validation and JavaDoc, please support  proposals at https://groups.google.com/forum/#!topic/checkstyle/VEVFDsZKLzg 

Comment viewing options

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