JSDoc Code Comments

Write JSDoc that helps the next developer understand the contract, intent, and surprising parts of JavaScript or TypeScript code.

Do not add comment noise. A good JSDoc block earns its space by saying something the signature, names, and nearby implementation do not already make obvious.

Workflow

1. Read the surrounding code before writing comments.
2. Identify the real documentation target: exported API, shared helper, class, component, hook, callback, type alias, object shape, or complex internal function.
3. Document behaviour and constraints before syntax details.
4. Prefer editing or deleting weak existing comments over stacking new comments on top of them.
5. Use /** ... */ JSDoc blocks immediately above the declaration they document.
6. Keep the first sentence useful as a standalone summary.
7. Add tags only when they clarify the contract.
8. Re-read the comment against the code and remove anything that is obvious, stale, vague, or unverified.

What Good JSDoc Explains