Debunking the Myth: Why Code Comments Often Do More Harm Than Good

In the ongoing debate over best practices in software engineering, few topics spark as much division as code comments. Should they explain complex logic? Document APIs? Or are they relics of an bygone era of low-level programming? Brian Walters, in a recent post on Nearform's digital community blog, cuts through the noise with a bold claim: the pervasive myth that "comments are a good way to provide additional context" must be purged.

![Main article image]()

Walters argues that in today's landscape of high-level languages like JavaScript and Python—with expressive variables, functions, classes, and design patterns—code should speak for itself. "Code don’t lie," he asserts, contrasting it with documentation that rots and comments that turn harmful. This shift from the days of C and Assembly, where proximity to hardware demanded extra context, means modern comments are often redundant, noisy, or outright misleading.

When Comments Fail: Real-World Pitfalls

Walters doesn't advocate a total ban on comments but insists they should be rare exceptions. Acceptable uses include:

• Copyright and authorship notes
• Explaining wonky syntax or confusing external APIs, like the infamous IE8 opacity hack:

.translucent {
  opacity: 0.25;
  -ms-filter: "progid:DXImageTransform.Microsoft.Alpha(Opacity=25)";
}

Such quirks warrant a note because the code alone can't convey Microsoft's arcane past. Similarly, public APIs in open-source projects like Symfony benefit from maintained comment-based docs, though Walters cautions this is a high-maintenance burden unfit for most teams.

“Clean code reads like well-written prose. Clean code never obscures the designer's intent but rather is full of crisp abstractions and straightforward lines of control.” — Grady Booch, creator of UML

However, most comments fall short. Walters categorizes their failures:

Noise Comments

useEffect(() => {
  // Check if window and window.dataLayer are available
  if (typeof window === "undefined" || !window.dataLayer) {
    
  }
}, []);

This adds no value—the code is self-evident. Refactor into a named function like isDataLayerAvailable() instead.

Misinformation Comments

interface User {
  id: string
  username: string
}

/**
 * Fetch the user information by their username
 */
export function getUserById(id: string): User {
  await fetch(...)
}

Here, the comment contradicts the function signature, forcing developers to distrust both.

TODO Comments and Commented-Out Code

TODOs are "wishes and dreams"—use tickets instead. Commented-out code is the "most harmful," as it bypasses type-checking and version control. Delete it; Git has your back.

Doc Comments and Whinging

![The Myth About Code Comments]()

Doc comments duplicate type signatures in private codebases, while "whinging" comments vent frustrations (e.g., "our backend is so slow"). These insult teams and distract from real fixes like refactoring.

The Better Alternative: Unit Tests as Documentation

Walters' core prescription? Prioritize self-documenting code via expressive naming, design patterns, and—crucially—unit tests. Tests provide verifiable examples, enable refactoring, and ensure code evolves without lies. Mandating comments, as one CTO did, signals distrust in developers' ability to write clean code, driving talent away.

For developers and teams embracing modern tooling—IDEs with static analysis, CI/CD pipelines—this means a cultural shift: comment less, refactor more. As Walters wraps up, comments are nuanced, but the myth of their universal value must die. In an era where code is the single source of truth, trusting it over supplementary text will yield cleaner, more maintainable systems—and happier engineers.

Source: The Myth About Code Comments by Brian Walters on Nearform, published February 28, 2024.