How to read and understand code comments and documentation

Comments Are Context, Not Descriptions

Good comments explain why something is done, not what the code does. The code already shows what — you can read it. The comment should tell you what you can't infer: business rules, workarounds, and non-obvious constraints.

Reading Structured Documentation

/**
 * Calculates the final price after applying promotional discounts.
 * Note: coupons stack multiplicatively, not additively.
 * See pricing spec: https://internal.wiki/pricing-rules
 *
 * @param {number} basePrice - Pre-tax price in cents
 * @param {string[]} couponCodes - Applied coupon identifiers
 * @returns {number} Final price in cents, minimum 0
 * @throws {InvalidCouponError} If any coupon code is expired
 */
function applyDiscounts(basePrice, couponCodes) { ... }

The most valuable part of this docstring is the note about multiplicative stacking — that's business logic that can't be inferred from the code itself.

TODO and FIXME Are Red Flags

// TODO: replace with proper pagination — added 2022-03-15
const users = await db.users.find().limit(1000);

// FIXME: race condition here under high load — ticket #892
if (!cache.has(key)) {
  cache.set(key, await fetch(key));
}

TODOs with dates and FIXMEs with ticket numbers are informative. Undated, unlinked TODOs are abandoned debt. When you encounter a FIXME, assume the described problem still exists until proven otherwise — treat it as an active bug.