Comments as Code Smell
debt(d5/e3/b3/t5)
Closest to 'specialist tool catches it' (d5). The term's detection_hints.tools lists phpcs, phpmd, phpstan which can flag some comment patterns (TODO without ticket, commented-out code blocks, excessive comment density), but nuanced judgment about whether a comment is genuinely redundant vs valuable 'why' context often requires human review. Automated detection catches the obvious cases but not the subtle smell.
Closest to 'simple parameterised fix' (e3). The quick_fix indicates refactoring code to be self-explanatory — this typically involves renaming methods/variables, extracting functions, or deleting redundant comments. Not a one-line patch (e1), but usually localized within a single component. Removing TODO comments or commented-out code is simpler; improving naming to eliminate what-comments requires more thought but stays within one file.
Closest to 'localised tax' (b3). Comment smell is a style/quality concern that affects readability but doesn't impose architectural weight. It applies across all contexts (web/cli/queue-worker) per applies_to, but poor commenting practices don't create load-bearing dependencies or shape the system's structure. The debt stays localized to the files where comments exist — fixing one area doesn't require touching unrelated code.
Closest to 'notable trap' (t5). The misconception states developers believe 'more comments always make code better' — this is a documented gotcha that experienced devs eventually learn, but juniors commonly fall into it. The trap isn't catastrophic (t9) because the failure mode is noise and drift, not broken functionality. Many developers have been taught to comment liberally and must unlearn that what-comments are harmful while why-comments remain valuable.
Also Known As
TL;DR
Explanation
Martin Fowler describes comments as a deodorant: they mask the smell of code that needs refactoring. A comment explaining what a function does suggests the function should be extracted and given a better name. Comments explaining why a non-obvious decision was made are valuable and should be kept. Outdated comments that contradict the code are worse than no comments. The goal is code so clear it needs no explanation, with comments reserved for intent that cannot be expressed in code.
Common Misconception
Why It Matters
Common Mistakes
- Adding comments to explain what a method does instead of improving the method name.
- Leaving TODO comments without a ticket reference or owner — they accumulate and are never addressed.
- Commented-out code left in production — use version control; dead code confuses readers.
- Block comments that restate the function signature: /** Gets the user */ function getUser() — zero information.
Code Examples
// Get the user
\$user = \$this->userRepo->find(\$id);
// Check if admin
if (\$user->role === 'admin') {
// Grant access
\$this->grantAccess(\$user);
}// Self-documenting — no comments needed
\$user = \$this->userRepo->findOrFail(\$id);
if (\$user->isAdmin()) {
\$this->grantAdminAccess(\$user);
}
// Comments add value when explaining WHY, not WHAT:
// 5-second delay: payment webhook arrives asynchronously;
// the DB write may not be committed when the redirect fires.
sleep(5);
\$order->refresh();