write-comments

Commenting

When to Comment

Code should be self-explanatory through good naming. Comments add value only when they explain why something is done — not what it does.

Comment when:

• Explaining non-obvious intent or business logic
• Documenting known edge cases or external constraints
• Noting a workaround with a link to the upstream issue

Don't comment when:

• The code is clear from reading it
• You're narrating what the code obviously does

How to Comment

Good Comments

// Delay is intentional: the third-party API enforces a 1s rate limit per key
await delay(1000);

// Uses linear search because this list is always < 10 items and never hot
const found = items.find((item) => item.id === targetId);

Bad Comments

// Increment counter
counter++;

// Call the API
const result = await fetchData();

// Return the value
return value;

Anti-Patterns

Obvious Comments

// Bad: restates what the code already says
const user = getUser(id); // Get the user by id

Redundant JSDoc

Avoid JSDoc on private functions or functions whose signature is self-documenting.

// Bad: JSDoc that adds nothing
/**
 * Gets the user.
 * @param id - The user id.
 * @returns The user.
 */
function getUser(id: string): User { ... }

// Good: JSDoc only when it adds non-obvious context
/**
 * Returns the user record, or throws `UserNotFoundError` if the id is
 * not present in the active-users projection. Does NOT check the archive.
 */
function getUser(id: string): User { ... }

TODO Comments

Don't leave TODO comments to bypass lint rules or defer real fixes.

// Bad: silences a rule without explanation
// eslint-disable-next-line @typescript-eslint/no-explicit-any
function process(data: any) { ... }

// Good: fix the underlying issue instead
function process(data: unknown) { ... }

If a TODO is genuinely needed (tracked work), include a ticket reference:

// TODO(#1234): remove once the upstream API supports batch deletes