Reading and Learning 'Clean Code' by Uncle Bob #Day_7

Welcome to Day 7 of the clean series. Here we have embarked on this journey to be a cleaner coder. Both with our code and mindset. Combined we become better professionals. To write these blogs, I'm reading two books. Clean Code and The Clean Coder, written by Robert C. Martin, also called Uncle Bob. Now, as we delve into Chapter 4 of "Clean Code" by Uncle Bob, we encounter the subject of "comments." While the topic of comments may seem straightforward, it is a crucial element in the art of writing clean and maintainable code. In this installment, we'll uncover the true essence of comments, dissecting when and how to use them effectively.

Chapter 4: Comments

"Don’t comment bad code, rewrite it." – Brian W. Kernighan and P. J. Plaughter

Pursuing excellence in every line we write is one of the fundamental concepts of clean code. Commenting should be a reflection of the quality of the code, not a Band-Aid solution for bad code. Let's analyze why.

The Double-Edged Sword of Comments

Comments, as described in the software development world, are often labeled as a "necessary evil." But why is that the case? Robert C. Martin provides us with valuable insight that comments exist to compensate for what we fail to express in our code.

Good Comments

Not all comments are created equal. The real art lies in crafting comments that add value rather than noise to your codebase. Here's a breakdown of categories where comments shine:

• Legal Comments: In some cases, corporate standards may require copyright or authorship statements. However, where possible, external documents should be referenced.

• Informative Comments: Information about a function or block of code can be useful. However, it's crucial to question whether expressing this information in comments is genuinely necessary.

• Explanation of Intent: Comments can be invaluable in explaining why a particular approach was chosen or why a specific output is desired. They provide insight into the "why" behind the code.

• Clarifications for Unmodifiable Code: In situations where you're working with libraries or code you cannot alter, clarifying comments can be a lifesaver. However, be aware that substantial risk is associated with clarifying comments, as they could become incorrect over time.

• Warning of Consequences: Sometimes, a straightforward comment serves as a warning, making it clear what could go wrong if certain actions are taken.

Bad Comments

• Mumbling: Are you trying to explain something but with ambiguity? Are you talking to the point? Do you really need that comment? Did you just mumbled?

• Redundant Comments: Have you already explained this thing in previous comments? Why are explaining the same things again and again with every function? Was the specification needed again with this child class?

• Misleading Comments: How many days it have been since you wrote this code? Why the comment doesn't match with the process it has been written for? Why did it match before but now does not? Wasn't that misleading?

• Mandated Comments: Why are you explaining the basic logic of the language and syntax? Why are you creating a bunch of clutter?

• Journal Comments: Are living in the 80s? Do you think you need to create logs through comments every time for the library you are creating? Do you understand how clutter is created?

• Noise Comments: Oh I skipped over a bunch of lines, does it matter? No, they were useless comments.

My Opinion

As you embrace clean coding practices, consider this: think before writing a comment. Ask yourself, can you express yourself better in the code itself? Comments should be your last resort, not your first line of defense.

In conclusion, comments, when used thoughtfully and sparingly, can enhance the readability and maintainability of your code. They are not mere annotations but a reflection of the clarity and expressiveness of your code. Remember, "Don't comment bad code, rewrite it." This advice, combined with the wisdom shared in "Clean Code," guides us toward cleaner, more maintainable software.

I hope this was as insightful for you as it was for me. In the next blog, we'll take the 4th chapter from the book, 'The Clean Coder'. Till then, Happy Clean Coding!