Code commenting practices
1. Comments are not subtitles
BAD:
|
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 |
|
BAD 2: “The Code Hoarder”
1 2 3 4 5 6 7 8 |
|
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.
Last updated