Clean code Chapter 4: How to write good Comments

the book discourages you to write comments, because if you wrote good, clean, and informative code, you shouldn’t need to have comments in the first place.

if we write good variable and function names, comments are not necessary.

Bad Comments

• Any comment that makes you looking in another file for the meaning of that comment
• Noise/Redundant comments: The comment is not more informative than the code

/**

* The day of the month

*/

private dayOfMonth: Int

• Don’t use comments when you can use function or variable names
• commented out code
• Too much information

Good comments

• Legal comments. Like copy right information.
• Informative comments. a date time format kk:mm:ss EEE, MMM dd, yyyy for example.
• Explanation of intent, we should explain our intent in the comments for example what’s the number 25000.
• Clarification. The book of course is in java and the example they used is

assertTrue(a.compareTo(b) == -1); // a < b

assertTrue(aa.compareTo(ab) == -1); // aa < ab

• Warning of consequences. For example, if a function is not thread safe

The book also mentioned that TODO comments are good comments I am not totally agree with this.

Because TODO comments discourage us and opt for filing technical debt(explained in the chapter 1).