"Clean Code" Book Summary - Part 3.

In this chapter, Uncle Bob introduces a new mind blowing concept that most programmers might not be used to: Comments are a necessary evil, in his book he says:

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 oldcrufty comment that propagates lies and misinformation.

And Why is that? because:

Programmers can’t realistically maintain comments.

lets discover together what are the best practices for using comments to write clean code.

Part 3 - Comments

• Comments are a necessary evil, we should be writing functions in a descriptive way, so that we can avoid writing comments at all, so the ideal case is that there should be no comments at all!.

• Comments should be used only as an explanation , never add obsolete code as a comment, instead remove it and depend on version control systems to preserve the history of the code.

• TODO comments are ok because the IDE can find them easily before ending the project.

• Don't write redundunt comments, if the code is self explanatory no need to add comments.

• Its a wrong concept that every function should have javadoc for documentation purpose, its better to have descriptive names than having a javadoc.

• Instead of using comments as function headers, replace them with a descreptive name for the function if possible.

• Instead of writing a comment to explain a long line of code, divide this line into more simpler lines by using local variables so as to make the code more descriptive and readable.

• Position markers like this:

  \\The following are the private methods\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\

  are ok, as long as they are not execcisvely used, otherwise the eyes will be trained to ignore them automatically, use them rarely in cases you need to put an important distinction.

• Attribute comments like: /* added by john smith on 1/10..*/ are ok but not to be a MISLEADING info or to be execcisve.
• Again, NEVER retain commented out code
• Don't put in a comment non local information, i.e. information that are not in the same context of the line,like e.g. something related to the whole program or to the whole module etc..
• Don’t put interesting historical discussions or irrelevant descriptions of details into your comments
• Don't put comments that have poor or no connection to the code it explains.

Continue to Part 4

Start the summary from here.