Code commenting practices

1. Comments are not subtitles

BAD:

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

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 (don’t try to pay attention to your code with drawing monkeys, smiles etc.)

3. Header Blocks: Nuisance or Menace?

1) Blocks of header comments at the top of every file, method or class 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.

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

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

BAD 1: “The Historian”

1 2 3 4 5 6 7 8 9

// 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() { ... }

BAD 2: “The Code Hoarder”

1 2 3 4 5 6 7 8

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); } }

5. Comments are a code smell

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.