bkinsey808/code-comment-best-practices

Requires: file-read. No terminal needed unless validating after edits.

Depends on: typescript-best-practices/SKILL.md — load when comment changes are driven by API clarity or type changes.

Full reference

docs/code-comment-best-practices.md — load on demand for detailed formatting patterns, examples, and edge cases.

When invoked

Preconditions:

• Read the file being commented before making changes.
• Check docs/ai/rules.md for repo-wide constraints.

Clarifying questions:

• Defaults (proceed without asking): add/update comments in the file already open; follow all rules below.
• Always ask: which file if not specified.

Output format:

• Write changes directly; after edits output a brief bullet list of what was added/changed and why.
• For question-answering: concise prose with inline code, referencing the relevant doc section.

Error handling:

• If lint or tsc fails after comment edits, report verbatim and fix before declaring success.

Quick rules

Core philosophy: explain the "why," not the "what." (philosophy)

• JSDoc (/** */) for exported functions, components, and types. (when to use)
• JSDoc requirement: Every exported function must have JSDoc. Additionally, any non-trivial internal function (complex logic, side effects, branching, or >~3 lines) should include concise JSDoc. Prefer documenting intent and side-effects over implementation details.
• Default to JSDoc for named functions you add — not just exports. Helper functions, local utility functions, test helpers, and hook-internal handlers should usually get concise JSDoc unless the name and body are truly trivial. This repo prefers documenting function purpose proactively rather than only at module boundaries.
• // for logic blocks (useEffect, complex conditionals), test descriptions, and grouped constants. (inline comments)
• No types in JSDoc — TypeScript provides them. Use @param name - description only. (formatting)
• Always @returns — write @returns void for void functions. (params & returns)
• Props: document fields directly — no @param props wrapper; list each destructured field. (params & returns)
• Multi-line JSDoc: /** and */ each on their own line. (formatting)
• One blank line above a JSDoc block; no blank lines between JSDoc and its symbol. (spacing & placement)
• No JSDoc above describe/it/test — use // only when the name isn't self-explanatory. (test comments)
• Grouped constants — use // above the group, not JSDoc spanning multiple symbols. (constants)
• Symbol comments: If a comment documents a specific symbol (function, constant, type, class, or exported value), use JSDoc (/** ... */) rather than //. Reserve // for inline implementation notes and small logic comments. This keeps symbol-level documentation consistent and machine-readable.
• Avoid repeating the symbol name: The first sentence of a symbol's JSDoc should be a concise verb phrase describing its purpose (e.g., "Return the user's profile"), not a restatement of the symbol name (avoid: "User profile: returns..." or "Noise filter: ..."). This keeps inline documentation focused and avoids redundancy.
• Max 100 chars per line. (formatting)
• JSDoc for any comment with a URL — use @see for standalone links (URLs, file paths), {@link} for inline symbol refs; never // for comments containing links. (links in comments)
• TODO/FIXME must include context — // TODO: [action] — [reason or ticket]; switch to JSDoc when the comment includes a link. (inline comments)
• No redundant comments — don't comment obvious code, don't repeat types, don't apologize for messy code (refactor instead). (what not to comment)
• Writing style — full sentences + periods for JSDoc; fragments ok for //; active voice; present tense; one space after //. (writing style)
• Anti-patterns — no commented-out code, no version history, no author attribution, no jokes or passive-aggressive remarks. (anti-patterns)

Validation

npm run lint

Do not

• Do not violate repo-wide rules in docs/ai/rules.md.
• Do not change logic — comments only.
• Do not add types in JSDoc for .ts/.tsx files.
• Do not expand scope beyond the requested task without calling it out.

Skill handoffs

• For TypeScript API clarity issues, also load typescript-best-practices.
• For React hook or component comments, also load react-best-practices.

Evaluations (I/O examples)

Input: "Add JSDoc to all exported functions in src/utils/format.ts" Expected: Agent reads the file, adds JSDoc with correct param/returns rules (no types, destructured props, @returns void where applicable), runs lint + tsc, reports what was added.

Input: "How should I comment a useEffect block?" Expected: Agent answers in prose: use // above the useEffect, explain the why not the what, never on the same line. References §6 of the doc.

Input: "Add comments" (no file specified) Expected: Agent asks which file before proceeding.