Блог / JavaScript + Ajax / Beyond "Self-Documenting" Code: The Lost Art of Intentional Commenting

Beyond "Self-Documenting" Code: The Lost Art of Intentional Commenting

### The "self-documenting code" mantra, while promoting clean coding practices, has an unintended side effect: a devaluation of good comments. This article argues that code can only ever document the "what," not the "why." We'll explore where self-documenting code falls short and provide a practical guide to writing intentional, high-value comments that improve maintainability and team collaboration for the long term.

Introduction In the world of software development, "write self-documenting code" is a piece of advice we hear so often it's become dogma. The idea is simple and alluring: if you use clear variable names, small functions, and logical structures, your code should be so transparent that it needs no explanation. No more tedious comments to write or, worse, to keep updated. And to be clear, this is a fantastic starting point. Clean, readable code is the foundation of any maintainable system. But somewhere along the way, this principle has been misinterpreted as "never write comments." We've become so focused on the *what*—the mechanical execution of the code—that we've forgotten the most critical element for future developers (including our future selves): the *why*. This article dives into the fallacy that clean code alone is sufficient documentation. We will explore the vital context that code can never convey and rediscover the lost art of writing intentional comments that add real, lasting value. ---

The Allure and Merits of Self-Documenting Code

Before we critique the concept, it's essential to understand its strengths. The push for self-documenting code came from a real problem: legacy codebases littered with useless or misleading comments.

What We Mean by "Self-Documenting"

Self-documenting code relies on a set of best practices to enhance clarity:

* **Descriptive Naming:** Using calculateSalesTaxForOrder instead of calc(data).

* **Small, Single-Responsibility Functions:** A function should do one thing and do it well. This makes its purpose obvious from its name.

* **Consistent Structure:** Following established design patterns and maintaining a logical flow within a class or module.

* **Avoiding "Magic Numbers":** Replacing a raw number like 86400 with a named constant like SECONDS_IN_A_DAY. These practices are non-negotiable for professional developers. They reduce cognitive load and are the first line of defense against chaos.

The Unquestionable Benefits

When done right, this approach leads to:

* **Improved Readability:** New developers can grasp the flow of the code more quickly.

* **Reduced Redundancy:** You avoid comments that simply parrot the code, like i++; // Increment i.

* **Single Source of Truth:** The code itself is the documentation, so there's no risk of comments becoming outdated when the code changes. But this is where the story ends for many developers. They stop here, believing the job is done. The reality is, this is just the beginning. ---

The Cracks in the Foundation: Where Code Fails as Documentation

Code is brilliant at telling you *what* it is doing. It is utterly incapable of telling you *why*. This is the crucial gap that even the cleanest code cannot bridge.

Explaining the "Why," Not Just the "What"

Consider this seemingly simple JavaScript function:

function calculateOrderTotal(items) {
  // Use integer math to avoid floating-point inaccuracies with currency.
  // We'll process everything in cents and convert back only for display.
  const totalInCents = items.reduce((acc, item) => {
    const itemPriceInCents = item.price * 100;
    return acc + (itemPriceInCents * item.quantity);
  }, 0);

  return totalInCents / 100;
}

The code is clean. The function and variable names are descriptive. It's "self-documenting." But without the comment, a future developer might ask:

* "Why are we multiplying and then dividing by 100? Why not just work with floats?"

* "This seems inefficient. Maybe I can 'optimize' it by removing the multiplication." The comment preempts these questions. It explains the **intent** and the **constraint** (avoiding floating-point errors with money), which is crucial business context that the code itself cannot communicate. This single comment saves hours of future head-scratching or, worse, the introduction of a subtle bug.

Documenting Business Logic and Technical Trade-offs

Your codebase is a living history of decisions, compromises, and external constraints.

* **A Quirky API:** "We have to call api.sync() twice here because the first call only warms up the cache and the second one returns the actual data. This is a known bug in v2.1 of the third-party library."

* **A Performance Optimization:** "This algorithm looks more complex than a simple loop, but it reduces the complexity from O(n^2) to O(n log n), which is critical for the 'large-dataset' report."

* **A Business Rule:** "Users with a 'gold' status get a 10% discount, but only on items that aren't already on sale. This logic was mandated by the marketing department on Q3 2023." This context is impossible to glean from the code alone. Without comments, a developer might try to "fix" the "redundant" API call or "simplify" the complex algorithm, inadvertently re-introducing a performance bottleneck.

Signposting and Future Warnings

Comments are invaluable for leaving breadcrumbs for your team and your future self.

# TODO: This is a temporary solution until the new authentication service is live.
# Expected to be replaced in sprint 45. See ticket JIRA-123.
def temporary_user_lookup(user_id):
    # ... implementation ...

# HACK: The UI library we use doesn't support async validation, so we are manually
# triggering a re-render here. This should be removed when we upgrade to v4.
def force_ui_update():
    # ... implementation ...

These "signpost" comments—like TODO, FIXME, or HACK—provide a roadmap of technical debt and planned improvements. They link code to project management tools and strategic decisions, creating a richer, more navigable codebase. ---

The Art of Intentional Commenting: A Practical Guide

The goal is not to write *more* comments, but to write *better* comments. Here's how to do it.

Rule 1: Comment the "Why," Not the "What"

**Bad Comment (The What):**

// Loop through the customers
foreach (var customer in customers)
{
    // ...
}

**Good Comment (The Why):**

// We need to process each customer individually to build a custom email
// payload, as the batch processing API was deprecated due to security concerns.
foreach (var customer in customers)
{
    // ...
}

Rule 2: Document the Non-Obvious

If a piece of code makes you stop and think for more than a few seconds, it probably needs a comment. This is especially true for:

* **Complex Regular Expressions:** A regex is the definition of "write-only" code. A brief comment explaining what it's trying to match is a kindness to everyone.

* **Mathematical Formulas:** Unless it's simple arithmetic, explain the formula and where it came from.

* **Workarounds:** If you're doing something weird to get around a bug in a framework or library, document it.

Rule 3: Don't Use Comments as a Crutch for Bad Code

If you find yourself writing a long paragraph to explain a convoluted function, the problem isn't the lack of comments—it's the code itself. Always refactor complex code *first*. Then, add a comment to explain any remaining "why" that isn't obvious. ---

Conclusion Clean code and intentional comments are not opposing forces; they are partners in creating truly maintainable software. While "self-documenting" code lays the foundation by making the *what* clear, high-value comments build upon it by explaining the *why*. By embracing this partnership, we can move beyond simplistic mantras and create codebases that are not only readable today but are understandable, maintainable, and adaptable for years to come. The next time you solve a tricky problem, make a necessary trade-off, or implement a non-obvious business rule, take an extra thirty seconds. Leave a comment. Your future self will thank you. --- For questions or feedback, please contact me at: isholegg@gmail.com.
**Keywords:** self-documenting code, code comments, clean code, software documentation, best practices, code readability, maintainable code, software engineering, programming principles, technical debt.
**Meta ** Explore why the "self-documenting code" mantra is not enough. Learn the art of writing intentional comments that explain the "why," not just the "what," to create truly maintainable software.

Якщо у вас виникли питання, вбо ви бажаєте записатися на індивідуальний урок, замовити статтю (інструкцію) або придбати відеоурок, пишіть нам на:
скайп: olegg.pann
telegram, viber - +380937663911
додавайтесь у телеграм-канал: t.me/webyk
email: oleggpann@gmail.com
ми у fb: www.facebook.com/webprograming24
Обов`язково оперативно відповімо на усі запитіння