← All articles
Software Development3 min read

12. Don't Use Comments

Comments are often unnecessary or misleading, and wrong comments are worse than none. Write self-explanatory code — and reserve comments for the rare cases that truly need them.

Delft-blue tile reading "Don't Use Comments"

Adding comments to your code may seem professional and helpful. But in practice, comments are often unnecessary—or worse: misleading. During refactors, comments are frequently left behind, making them outdated or incorrect. And let's be clear: wrong comments are always worse than no comments at all.

That's why I say: don't use comments.

Instead, make sure your code is self-explanatory. Use clear names, logical structure, and clean architecture. Good code explains itself.

If you feel you need a comment to make something understandable, that's usually a sign your code should be rewritten.

❌ A typical example of a useless comment:

/**
 * arc
 * @param x
 * @param y
 * @param radius
 * @param startAngle
 * @param endAngle
 */
function arc(x, y, radius, startAngle, endAngle) {
  ...
}

This comment block adds nothing. It simply repeats what's already obvious from the function signature and doesn't explain anything meaningful.

Another great example I found recently on LinkedIn: 🔗 LinkedIn post by Vlad Mihalcea

AI tools are also known for generating excessive and meaningless comments. That's why I always instruct them explicitly: do not generate pointless comments.

✅ When are comments useful?

Of course, there are exceptions. Some situations do benefit from well-placed comments:

  • 📦 Public APIs of widely used libraries. Clear documentation of functions, parameters, and return values is essential for other developers.
  • ⚠️ Unusual or non-obvious code. If something breaks the expected pattern or logic, explain why it's done that way.
  • 🔍 Complex regular expressions. Regex is notoriously hard to read. A brief explanation of what it does can save a lot of headaches.

And also:

  • 🧠 Workarounds for external bugs. If you're writing code to deal with a browser issue, library bug, or platform quirk, make that context explicit.
  • 🧪 Non-intuitive optimizations. Sometimes you deliberately choose "weird" code for performance or security. A quick note helps others understand.
  • 🧾 Complex business rules. For example, tax rules or regulatory conditions that affect the logic—point to the source and explain the reasoning.
  • ⏳ Temporary hacks or quick fixes. Use TODO: or FIXME: along with a note on why it's temporary, and when or by whom it should be addressed.
  • 📚 References to decisions or documentation. Think of links to tickets, architecture decisions, or wikis—helpful for understanding the history behind the code.

But even in these cases: 👉 Make sure the comment is correct, up-to-date, and adds real value.

📝 TL;DR

First, write clear code.

Only add comments when they genuinely help the reader understand something that the code can't express well on its own.

What about you? Do you rely on comments in your code? 😉 Worth a moment of honest reflection. 💬

👨‍🏫 Need help writing clean, maintainable code? Feel free to reach out—I'd be happy to help.

Related articles