Comment Generation

Generate doc comments for non-obvious functions; skip trivial ones and avoid noise.

Docs & RefactorBeginner

Why

GitHub's 2024 survey found 81% of developers expect AI tools to become more integrated in documenting code over the next year, the highest of any workflow. Good doc comments help readers and AI context; bad ones ('increment x by 1') are noise.

Generating for non-obvious functions only, with intent + edge cases, adds signal without clutter.

When

Use on undocumented non-trivial functions. Skip trivial getters/setters.

How

1. List functions without doc comments. 2. Prompt: "add JSDoc with @param/@returns and intent; skip obvious ones; include edge cases". 3. Review each; delete any that just restate the code. 4. Run tsc (JSDoc is type-checked in strict mode). 5. Commit docs: add JSDoc to <module>.

Example

Before: export const parsePage = (input: string | null): number => { ... } After: /** Parse a ?page= param into a 1-based page (min 1); null/invalid → 1. */ export const parsePage = (input: string | null): number => { ... } Skip: export const getId = (x: { id: string }) => x.id; // obvious, no comment.

Common Problems

⚠Error: Cannot find module 'xxx' after refactor → re-run `npm install` and `npx tsc --noEmit`; refactors often drop or rename imports.
⚠Error: "Cannot read properties of undefined" after refactor → run the test suite (`npm test`) to catch behavior changes; refactor must be behavior-preserving.
⚠Error: Docs drift: example no longer runs → execute examples in CI (`npm run docs:check`); tested examples never drift.

Best Practices

✓Document intent and edge cases, not what the code does.
✓Skip trivial functions; noise hurts readability.
✓Measure the outcome with a concrete metric (time saved, defect rate, test coverage) so the practice can be justified and improved.

FAQ

What is Comment Generation?

Generate doc comments for non-obvious functions; skip trivial ones and avoid noise. It helps developers quickly grasp the core value and use cases of Comment Generation.

How do I get started with Comment Generation?

To get started with Comment Generation, focus on these points first: List functions without doc comments.

What are common mistakes with Comment Generation?

Common mistakes when using Comment Generation include: Error: Cannot find module 'xxx' after refactor → re-run `npm install` and `npx tsc --noEmit`; refactors often drop or rename imports.; Error: "Cannot read properties of undefined" after refactor → run the test suite (`npm test`) to catch behavior changes; refactor must be behavior-preserving.; Error: Docs drift: example no longer runs → execute examples in CI (`npm run docs:check`); tested examples never drift..

What are the best practices for Comment Generation?

Best practices for Comment Generation include: Document intent and edge cases, not what the code does.; Skip trivial functions; noise hurts readability.; Measure the outcome with a concrete metric (time saved, defect rate, test coverage) so the practice can be justified and improved..

How do I learn more about Comment Generation?

Start with the official docs, then search real-world examples on GitHub. Validate patterns in a small scratch repo before applying them to production code.