Beyond the "What": Why Good Code Comments Remain Indispensable

The discussion around code comments—whether they are a necessity or a hindrance—continues to evolve. While the goal of writing clean, self-documenting code is laudable, it's widely agreed that comments still hold significant value, particularly for explaining aspects that the code itself cannot.

A primary theme is the distinction between what the code does and why it does it. Code naturally describes the "what," but comments excel at clarifying the "why"—the underlying design decisions, non-obvious hidden assumptions, historical context for specific values, or workarounds for particular issues. This "why" information is crucial for developers revisiting code after a long period, essentially serving as notes from "past you" to "future you." These types of comments often have a longer shelf-life than comments merely rephrasing code, as the reasoning behind a piece of logic tends to change less frequently than the implementation details during refactoring.

Some developers argue that comments are a maintenance burden and can become stale or incorrect, which is indeed worse than no comment at all. However, proponents emphasize that the benefits of well-placed, meaningful comments far outweigh this potential cost. The argument that self-documenting code eliminates the need for comments is often countered by the fact that code alone cannot express intent, trade-offs, or external dependencies.

There's also a debate about where this "why" information should reside. While some suggest that high-level design decisions and hidden assumptions belong in external documentation (like READMEs or dedicated .md files) to avoid mixing natural language with programming language within the code, many find in-line comments invaluable for immediate context.

Beyond explaining "why," specific types of comments prove particularly useful:

Temporary Code Warnings: Comments like # If you see this after 2008, something went wrong provide explicit signals for code intended to be short-lived, prompting future cleanup.
Dependency and Troubleshooting Clues: Notes about external dependencies, configurations, or potential issues can save significant time during debugging or 3 AM outages.
Historical Context and Rationale: Explaining why a specific value or setting was chosen can prevent future developers from blindly altering it, often referred to as avoiding "cargo culting."
Links to External Systems: Many teams use comments to reference Jira issue numbers, Confluence pages, or other external documentation, bridging the gap between code and project management.

Ultimately, the goal isn't to comment every line, but to selectively apply comments where they add clarity, explain intent, or provide context that the code cannot inherently express, ensuring maintainable and understandable software for everyone, including your future self.