Comment Quality

Obvious comment — the most common comment anti-pattern. The comment adds no value; anyone who can read code already knows x = x + 1 adds 1 to x.

Fix: either delete the comment, or replace it with a WHY comment:
• x = x + 1; // advance past the BOM character at offset 0
• x = x + 1; // skip index 0 — reserved for the null sentinel value

Comment quality anti-patterns:
1. Obvious comment: restates the code ("add 1 to x")
2. Lying comment: describes different behavior than what the code does
3. Journal comment: "Added by Alex on 2023-07-14" — use git blame instead
4. Commented-out code: dead code left in the file — delete it, git history preserves it
5. Noise comment: empty, placeholder, or meaningless ("TODO: fix later")

When code is well-named and obvious, no comment is the best comment.

Lying comment — the most dangerous comment anti-pattern. The comment says "Validates the user input" but the function actually charges the card (and applies a 1.2× multiplier — possibly undocumented tax or fee).

Lying comments cause bugs because developers trust comments over code when they conflict. A developer might rely on "validates input" without reading the implementation, leading to double-charging, missing validation, or both.

How lying comments happen:
• Code was changed after the comment was written, but the comment was not updated
• Comment was copied from another function
• Developer described intent rather than actual behavior

Fix:
1. Delete the lying comment
2. If validation is needed, add it (the comment may describe a missing requirement)
3. Write an accurate comment: "// Charges the card amount plus 20% tax and fee surcharge"

Rule: if you change code that has a comment above it, you MUST update or delete the comment.

Journal / changelog comments — an anti-pattern that pollutes source code with information that git already tracks far better.

Problems:
• Git blame and git log already record who changed what, when, and why (in the commit message)
• These comments grow over time until they exceed the actual code in length
• They are never kept fully up to date
• They add noise when reading the code

What to do instead:
• Write meaningful commit messages: "fix: resolve memory leak in cache eviction (see #891)"
• Use git blame to see who last changed each line
• Use git log --follow -p -- src/cache.js to see full file history
• Reference ticket/issue numbers in commit messages for traceability

The only time author+date in code is acceptable: legal/licence headers required by open-source licences, or regulatory environments where source-level audit trails are mandated by external compliance requirements.

Delete it — commented-out code is one of the clearest code smell anti-patterns.

Why delete, not keep:
• Git history preserves the code — use git log or git show <commit> to retrieve it anytime
• Commented-out code creates confusion: "Is this intentionally disabled? Is it a WIP? Is it broken?"
• It adds noise to every code review, every search, every refactor
• Over time, commented-out code becomes so stale it would need rewriting anyway

When you are about to comment out code, ask:
• "Am I going to need this again?" → If yes, keep it in a feature branch
• "Is this a WIP?" → Use a WIP commit in Git, not commented-out code
• "Should I preserve this?" → Already in git history

The only acceptable commented-out code:
• A // TODO: uncomment when feature X ships for a very short time frame, with a linked issue
• Example code in docs/comments that should NOT be run automatically

Option B transforms a vague "important" into an actionable security note that tells developers:

1. What this does: "all requests must pass this point" — establishes the scope
2. The explicit warning: "DO NOT bypass" — direct instruction
3. The consequence: "skipping JWT verification exposes all endpoints to anonymous access" — makes the risk concrete

"This is important" is a noise comment because:
• "Important" is relative and undefined
• It gives no guidance on what would happen if this was changed
• A future developer has no idea WHAT is important about it

Rewriting bad comments — the process:
1. Ask: WHY is this important? What constraint does it represent?
2. Ask: What would break if this was removed or changed?
3. Write: statement of constraint + DO NOT + consequence of violating it

Pattern: // NOTE: [what this is] — [explicit warning] — [consequence of changing it]

Non-obvious algorithms — the primary legitimate use case for dense commenting.

Examples where line-by-line commenting is genuinely valuable:
• Cryptographic algorithms (each step has a security reason)
• Bitwise operations and bit manipulation tricks
• Cache-oblivious algorithms, SIMD optimisations
• State machine with subtle transition logic
• Numerical methods with convergence conditions
• Regex patterns that span multiple lines

Good algorithm comment example:

// Murmur3 hash finalisation mix
// Avalanche bits to ensure uniform distribution
// (see Appleby 2011, "MurmurHash3")
x ^= x >> 16;
x *= 0x85ebca6b;  // magic constant — provides good bit mixing
x ^= x >> 13;
x *= 0xc2b2ae35;  // second mixing constant
x ^= x >> 16;

The test: if a competent colleague would understand the code without a comment in 30 seconds, the comment is probably not needed. If it would take 10 minutes and a whiteboard, write the comment.