Comments in Programming

From Bee: Comments age badly. Every time you change code, scan the comments above and below it. Outdated comments are worse than no comments.

What Is a Comment?

A comment is text inside source code that the computer ignores when running the program. Comments exist for humans — your future self, your teammates, anyone reading the code in six months. The compiler or interpreter strips them out; they have zero effect on what the program does.

Comments are useful for three things: explaining why a piece of code does something non-obvious, leaving reminders or todos, and temporarily disabling code without deleting it.

Syntax in Three Languages

// Single-line comment
let total = 100; // Inline comment after code

/* Multi-line
   comment that spans
   several lines */

/**
 * JSDoc comment — used for documentation tools
 * @param {number} n
 */
function double(n) { return n * 2; }

# Single-line comment
total = 100  # Inline comment after code

# Python has no native multi-line comment.
# Convention: stack many # lines, or use a
# triple-quoted string (technically a string
# literal that gets discarded):

"""
This is often used as a multi-line comment.
"""

def double(n):
    """Docstring — describes what the function does."""
    return n * 2

// Single-line comment
int total = 100; // Inline comment

/* Multi-line
   comment */

/**
 * Javadoc comment — used by the documentation generator.
 * @param n the number to double
 * @return n times two
 */
public static int doubleIt(int n) { return n * 2; }

When to Write a Comment

Good code is mostly self-documenting through clear naming and small functions. Comments earn their keep when they explain things the code itself can't:

• Why a non-obvious choice was made. "We use a 3-second debounce because the upstream API rate-limits at 0.5 req/s."
• Workarounds for a specific bug or browser quirk. "Safari 15 has a bug with focus events on input[type=date] — hence the timeout."
• Constants whose meaning isn't obvious from the name. "Threshold of 0.83 — empirically the value with best precision/recall on our data."
• Public API documentation. Any function others will use should describe what it accepts and returns.

When NOT to Write a Comment

The most common beginner mistake is over-commenting. Don't restate what the code obviously says:

// BAD — comments add noise without information
let x = 5;          // Set x to 5
x = x + 1;          // Increment x by 1
return x;           // Return x

Compare with:

// GOOD — comment adds info you can't get from reading the code
let retries = 5; // 5 chosen to match payment provider's max attempts
while (retries-- > 0) {
  if (chargeCard()) return true;
}
return false;

Commenting Out Code

You can wrap code in comment syntax to temporarily disable it without deleting it. This is fine for short experiments. Don't ship code with large blocks of commented-out code — version control (git) tracks deleted code; commented-out blocks just clutter the file.

TODO and FIXME Comments

A widely-followed convention: prefix temporary reminders with TODO:, FIXME:, or HACK:. Most editors highlight these visually, and you can grep them later to find work that needs doing.

// TODO: switch to the new pricing endpoint when it's live
// FIXME: this breaks if the user has more than 1000 items
// HACK: padding by 2px to work around Safari rendering bug

A Small Mental Model

Best Practices

1. Comment why, never what — the code already says what.
2. Keep comments next to the code they describe.
3. Update comments when the code changes — outdated comments are worse than none.
4. Use docstrings for any function someone else will call.
5. Don't commit large blocks of commented-out code.
6. Use TODO/FIXME for known issues so you can find them later.

Quick Quiz

Real-World Uses (Production Code, Today)

Frequently Asked Questions

Related Concepts