robert martin on comments

i am reading the excellent book clean code (martin , 2009)

chapter 4 - "comments" has some excellent points about the role of comments in code and some good arguments and points that i had not considered. i thought i would share some key ideas presented and my additional thoughts.

{syntaxhighlighter style='brush: plain;'}Nothing can be quite so helpful as a well-placed comment. Nothing can clutter up a module more than frivolous dogmatic comments. Nothing can be quite so damaging as an old crufty comment that propagates lies and misinformation. Comments are not like Schindler’s List. They are not “pure good.” Indeed, comments are, at best, a necessary evil. If our programming languages were expressive enough, or if we had the talent to subtly wield those languages to express our intent, we would not need comments very much—perhaps not at all. The proper use of comments is to compensate for our failure to express ourself in code. Note that I used the word failure. I meant it. Comments are always failures. We must have them because we cannot always figure out how to express ourselves without them, but their use is not a cause for celebration. So when you find yourself in a position where you need to write a comment, think it through and see whether there isn’t some way to turn the tables and express yourself in code. Every time you express yourself in code, you should pat yourself on the back. Every time you write a comment, you should grimace and feel the failure of your ability of expression. Why am I so down on comments? Because they lie. Not always, and not intentionally, but too often. The older a comment is, and the farther away it is from the code it describes, the more likely it is to be just plain wrong. The reason is simple. Programmers can’t realistically maintain them. Code changes and evolves. Chunks of it move from here to there. Those chunks bifurcate and reproduce and come together again to form chimeras. Unfortunately the comments don’t always follow them—can’t always follow them. And all too often the comments get separated from the code they describe and become orphaned blurbs of everdecreasing accuracy. {/syntaxhighlighter}

comments do not make up for bad code: {syntaxhighlighter style='brush: plain;'}Clear and expressive code with few comments is far superior to cluttered and complex code with lots of comments.{/syntaxhighlighter}

goes without saying...at the same time, the reverse is not true - just because you do not comment does not mean your code is clear and expressive.

on mandated comments: {syntaxhighlighter style='brush: plain;'}It is just plain silly to have a rule that says that every function must have a javadoc, or every variable must have a function{/syntaxhighlighter}

comments are noise: most IDEs can be set to automatically collapse comments {syntaxhighlighter style='brush: plain;'}(sometimes comments are just ) misplaced desire to provide documentation{/syntaxhighlighter}

also to be avoided are:

• attributes/bylines ie) /* this code added by Archie */
• commented-out sections of code
• file change journals ie) /* 01-02-99 did this*/ /* 03-04-99 did that*/

all of these can be handled by version control systems, as my favorite quote of the chapter states: {syntaxhighlighter style='brush: plain;'}There was a time back the the sixties, when commenting-out code might have been useful. But we've had good source control systems for a very long time now.{/syntaxhighlighter}

haha. i find this quote hilarious...because it hurts.

To explain yourself: {syntaxhighlighter style='brush: plain;'}In many cases it's simply a matter of creating a function that says the same thing as the comment you want to write.{/syntaxhighlighter}

indeed, refactoring code down to 20-30 line functions enables this. as does expressive naming of variables and functions.

the school of thought has changed. what used to be considered "well documented" as martin puts it, is now seen as unclean. and unclean works against the developer - muddying up the readability and understandability of the code.