Overview

Every comment should earn its place. A good comment provides context the code alone cannot convey — why a decision was made, what trade-off was accepted, or how a non-obvious piece fits the bigger picture. A comment that merely restates the code is noise; remove or avoid it. When in doubt, prefer no comment over a redundant one.

Guidelines

• Comment only when needed. Do not add comments or JSDoc unless the code is non-obvious or you are explicitly asked. Self-explanatory code needs no narration.
• Inline comments: ≤ 2 lines. Keep them terse — explain why, not what.
• JSDoc: comprehensive yet concise. Document only what adds value: purpose, non-obvious parameters, return semantics, or usage examples. Omit what the signature already communicates.
• Use /** ... */ for reusable symbols. Functions, types, and constants referenced elsewhere should use JSDoc so IDE hover tooltips display the information.
• Document trade-offs. When the implementation accepts a trade-off, explain the rationale and why it was worth taking.
• No assumptions. Ground comments in library docs, project standards, or best practices — not guesses. Ask for clarification when unsure.
• Stay consistent; never contradict. Match the tone and terminology of existing comments. Do not duplicate information already stated in a nearby comment — reference it instead.

Example

The annotated snippet below highlights common comment pitfalls alongside good practice.