Series Clean Code - Comments

Continue the Clean Code series, today I'll talk about Comments topic. As we know, Comments can be very useful if placed in the right place, but it can also get worse, causing disturbed distrust when misplaced or providing inaccurate information. Using comment as an offset for failure in rendering code, we must use it because we can not always find a way to render the code.

Comments Do Not Make Up for Bad Code

• Comment is not used to decorate bad code. 
• One of the common motivations for writing comments is bad code. 
• We write a module and we know that it's messy and disorganized, we know it's a blast, so we say to ourselves, "Ohh, I should comment it!" >> No, it should be cleaned up! 
• Cleans and expresses the code along with a few better comments that are messy code with a bunch of comments. 
• Instead of spending time writing comments for a mess, you should clean it up.

Explain Yourself in Code

• Code is the best explanation. 
• In many cases, replace the poor code by creating new functions that say enough about the comment you want to write for that poor code. 

 

Good Comments

• Legal Comments
• Informative Comments
• Explanation of Intent
• Clarification
• Warning of Consequences
• TODO Comments
• Amplification

Legal Comments

• This depends on the company's coding standards. 
• For example: Copyright and copyright are essential and reasonable to include in the comment at the beginning of each source file.

Informative Comments

• It is sometimes useful to provide basic information with a comment, but it is better to transfer information via the name of the function if possible >> responderBeingTested()

 

• Indicates the time format in the SimpleDateFormat.format function with a specified string. 

 

Explanation of Intent

•  Explain the purpose

 
Clarification

• Make clearly, clarify

 

Warning of Consequences

• Warning about the consequences

 

TODO Comments

• TODO is something that programmers think they should do, but for some reason they can not do it right now.

  

Amplification

• Used to amplify something important that it does not seem to matter.

 

Bad Comments

• Mumbling 
• Redundant Comments 
• Misleading Comments 
• Mandated Comments 
• Journal Comments 
• Noise Comments 
• Scary Noise 
• Do not Use a Comment When You Can Use a 
• Function or a Variable 
• Position Markers 
• Closing Brace Comments 
• Attributions and Bylines 
• Commented-Out Code 
• HTML Comments 
• Nonlocal Information 
• Too Much Information 
• Inobvious Connection 
• Function Headers

See you in next chapter about Formatting in Clean Code..