Chapter 4 of “Clean Code” tackles the tricky subject of comments. We all know comments can be helpful, but they can also make code worse if they’re not done right. The main idea? Good code should mostly explain itself. Comments should be used sparingly, and only when they truly add value. Let’s dive in.

Chapter 4 – Comments

• Comments Do Not Make Up for Bad Code: Okay, so the very first thing the book says is super important: if your code is a mess, adding comments isn’t going to fix it. Think of it like putting lipstick on a pig – it’s still a pig. The better solution is to clean up the code itself.
• Explain Yourself in Code: This is the core message: aim to write code that’s so clear and well-structured that it doesn’t need a lot of explaining. Use good names for your variables and functions, keep your functions small and focused, and follow the other clean code principles we’ve talked about.
• Good Comments: Now, the book does acknowledge that there are times when comments are useful. But they need to be the right kind of comments. Here are some examples of good comments:
  • Legal Comments: Sometimes you have to include comments for legal reasons, like copyright notices or licensing information. These are usually necessary, even if they’re not about the code itself.
  • Informative Comments: These comments provide basic information that might be helpful but isn’t immediately obvious from the code. For example, explaining the format of a date or the meaning of a regular expression.
  • Explanation of Intent: This is a really good use of comments. Sometimes, code can be a bit tricky, and it’s helpful to explain why you did something a certain way. What was the thinking behind this approach?
  • Clarification: Sometimes, a bit of code can be hard to understand, even if it’s well-written. A comment can help to clarify a complex or unusual situation.
  • Warning of Consequences: This is another important one. If a certain piece of code might have unintended consequences, a comment can warn other developers (and your future self!) about potential problems.
  • TODO Comments: These are those comments that say, “Hey, this needs to be done later.” They’re basically reminders of things that still need to be addressed. But the book warns against letting these pile up and become clutter.
  • Amplification: A comment can be used to amplify the importance of something that might otherwise be overlooked.
  • Javadocs in Public APIs: If you’re writing a public API (a library that other people will use), Javadocs (or similar documentation for other languages) are essential. They provide documentation about how to use your code.
• Bad Comments: Okay, so now we get to the stuff to avoid. The book lists a whole bunch of ways that comments can go wrong and actually make your code worse:
  • Mumbling: A comment that’s vague, unclear, or doesn’t make sense is worse than no comment at all. It just adds confusion.
  • Redundant Comments: These are comments that simply repeat what the code already says. For example: Java i++; // increment 1 That’s completely pointless.
  • Misleading Comments: This is a big one. A comment that doesn’t accurately describe the code is really dangerous. It can send people down the wrong path and cause bugs.
  • Mandated Comments: Some organizations have rules that require every function to have a comment, even if it’s obvious what the function does. These comments often just add clutter.
  • Journal Comments: These are comments that keep a running log of every little change that was made to the code. Version control systems like Git are much better for this.
  • Noise Comments: These are comments that add no real value. They’re just filler that makes the code longer and harder to read.
  • Scary Noise: Certain comments can be particularly bad, like those with lots of asterisks or other decorations that make them stand out but don’t actually say anything useful.
  • Don’t Use a Comment When You Can Use a Function or a Variable: This is a key point. If you have a complex piece of code that needs explaining, it’s often better to extract it into a separate function with a good name, or use a well-named variable.
  • Position Markers: Comments like //////// or -------- that are used to mark the beginning or end of a section of code can be distracting and unnecessary.
  • Closing Brace Comments: Some people put comments like } // end of if at the end of closing braces. This is usually redundant if your code is well-indented.
  • Attributions and Bylines: Comments that say who wrote the code or when it was written are usually better handled by version control systems.
  • Commented-Out Code: This is a big no-no. Don’t leave old, commented-out code in your file. It just adds clutter and makes it harder to see what’s actually important.
  • HTML Comments: Don’t put HTML tags in your comments, even if you’re working on a web project.
  • Nonlocal Information: A comment should only describe the code that’s right there. Don’t put information in a comment that applies to a different part of the system.
  • Too Much Information: Don’t cram a ton of information into a comment. Keep it concise and focused.
  • Inobvious Connection: If a comment is describing something that’s not immediately obvious from the code, make sure the connection is clear.
  • Function Headers: Function headers that just repeat the function signature are usually redundant.
  • Javadocs in Nonpublic Code: Javadocs are great for public APIs, but they’re often overkill for code that’s only used internally within your project.
  • Example: The chapter ends with an example of how to refactor code to eliminate unnecessary comments and make the code itself more self-explanatory.

At the end of the day, Clean Code doesn’t say “never write comments”, it says earn the right to use them. Comments are a tool, not a crutch. When used well, they clarify. When misused, they confuse. So before reaching for the //, reach for a better function name, a clearer structure, or a cleaner approach. Your future self—and your teammates will thank you.