6 exercises — practise the WHY not WHAT rule, choosing the right marker (TODO/FIXME/HACK), and writing comments that give future developers the context they need.
0 / 6 completed
1 / 6
You have this line of code:
`results = results.filter(x => x.status !== "deleted")`
Which comment follows the "WHY not WHAT" rule?
Option B explains WHY: "soft-deleted records are retained in the DB for audit; exclude from all API responses". This gives context that the code alone cannot convey — the business rule (audit retention), the architectural decision (soft delete), and the scope (all API responses).
The "WHY not WHAT" rule: • The code already tells you WHAT it does — you can read it • A useful comment tells you WHY — the intent, constraint, or reason that isn't obvious
Bad comment: // filter out deleted records — just restates the code Good comment: // soft-deleted items kept in DB for SOC2 audit trail; excluded from public API
When to write an inline comment: • Non-obvious algorithm or logic • Business rule that comes from requirements, not code • Workaround for an external bug or constraint • Magic number ("0.8" → "// 80% capacity threshold from SLA contract") • Warning about a subtle side effect ("// mutates the input array")
2 / 6
A colleague asks you to add a comment to this code:
`const MAX_RETRIES = 3;`
Which comment adds the most value?
Option C explains WHY the value is 3, not 1, 2, or 10. This is the best comment because it documents: 1. The empirical observation (vendor drops ~2% of requests) 2. The business reasoning (>99.9% success rate) 3. The source of the value ("empirically") — this came from testing, not guessing
This is the type of information that would otherwise live only in the head of the developer who wrote it, or in a Jira ticket no-one would find again.
Magic number commenting pattern: • const TIMEOUT_MS = 30000; // 30s — Firebase cold start latency; set empirically in load test • const BATCH_SIZE = 100; // DynamoDB write limit per batch request • const MIN_PASSWORD_LENGTH = 12; // NIST SP 800-63B recommendation
The value "3" in option C is a magic number only when seen without context. With the comment, it becomes a documented engineering decision.
3 / 6
You need to leave a comment about a known bug that you cannot fix right now because it requires a significant refactor. Which marker and wording is most appropriate?
Option B uses the conventional FIXME marker and provides all the information the next developer needs:
1. FIXME: — conventional marker for known bugs (visible in TODO/FIXME linters) 2. race condition — names the specific type of bug 3. when multiple requests arrive in the same millisecond — describes the triggering condition 4. needs mutex or atomic compare-and-swap — suggests two concrete solutions 5. see issue #4112 — links to the tracking issue for full context
FIXME best practices: • Be specific: describe what is broken and when it happens • Suggest a solution if you have one • Link to an issue/ticket if one exists • Optionally add your initials and date: // FIXME(alex, 2024-03): ...
Format: // FIXME: [what is wrong] — [when it happens] — [suggested fix or issue link]
4 / 6
When should you NOT write a comment?
When the comment restates the code — "noise comments" reduce readability without adding value.
Examples of noise (do NOT write these): • i++ // increment i • return null; // return null • user.save(); // save the user • // constructor above a constructor function • // getter for name above a getName() function
When to write comments (do write these): • Algorithm or logic that is non-obvious ✓ • External constraint or known bug workaround ✓ • Business rule not visible in the code ✓ • Warning about side effects or mutation ✓ • Explaining a deliberate performance trade-off ✓ • Citing a source for a magic number or formula ✓
The standard: if a competent developer in your team would understand the code without the comment, omit it. If the comment would prevent future confusion or incorrect changes, include it.
5 / 6
You need to leave a note about a security-sensitive section. Which comment is most effective?
Option C uses a SECURITY marker and explains the specific risk, the correct approach, and WHY the common alternative is dangerous — all in one actionable comment.
Security comments should be explicit about consequences: • // SECURITY: validate all user input before this point reaches the query builder • // SECURITY: do NOT log this value — it contains PII (GDPR Art.4) • // SECURITY: tokens expire in 15 min — do NOT extend; see auth spec §3.2 • // SECURITY: constant-time comparison required (see OWASP timing attack)
The constant-time comparison note in option C is a real, important pattern: normal string comparison (===) short-circuits as soon as it finds the first mismatch, so an attacker can measure response times to guess characters in a secret one by one. A constant-time function always takes the same time regardless of where the mismatch occurs, preventing the side channel.
6 / 6
You are writing a comment to explain a temporary workaround. Choose the best phrasing.
Option B is the best temporary workaround comment. It provides: 1. HACK: marker — signals temporary code to anyone reading or searching 2. What the workaround is — polling instead of webhooks 3. WHY it is necessary — Stripe sandbox limitation 4. Source — documentation link for verification 5. Removal condition — "remove when upgrading to live mode"
The removal condition is especially valuable: it transforms a vague hack into a task with a clear trigger. A future developer switching to live mode will search the codebase and find this exact note.
HACK / workaround comment format: // HACK: [what the workaround does] — [why it's needed] — [link to source/issue] — [when to remove]
Without clear workaround documentation, temporary code becomes permanent code — the developer who understands the context leaves, and no-one dares remove it.