What this prompt does
This prompt adds meaningful comments to a [language] codebase focused on [code_area], following [style_guide] and your team's [comment_style]. It targets the comments that actually help — the why behind complex logic and the edge cases — rather than restating what well-named code already says.
The structure works because it distinguishes signal from noise. It first generates [doc_format] annotations for undocumented public functions, classes, and methods, with parameter types, return values, thrown exceptions, and a one-line summary. For logic above a [complexity_threshold], it adds inline comments explaining the reasoning and any design decisions, not the obvious mechanics. It marks TODO/FIXME/HACK comments where it detects edge cases or assumptions that could break under [failure_scenarios], writes file-level module comments describing responsibility and dependencies, adds @example blocks with [example_count] patterns, and cross-references related code. A final rule ensures comments pass [lint_tool] and never duplicate clear naming.
When to use it
- You inherited code where the why behind complex logic is missing.
- Your public API in
[code_area]lacks[doc_format]annotations. - You want edge cases and risky assumptions documented as TODO/FIXME notes.
- You need file-level comments explaining each module's responsibility.
- You want
@exampleblocks showing real usage for utility functions. - Your team enforces documentation linting with
[lint_tool].
Example output
Expect annotated code rather than a separate document. Public functions, classes, and methods gain [doc_format] blocks carrying typed parameters, return descriptions, thrown exceptions, and a one-sentence summary. Logic above [complexity_threshold] gets inline comments that explain the reasoning and any design decisions behind the approach, not the obvious mechanics. Where the model spots edge cases or assumptions that could break under [failure_scenarios], it leaves TODO, FIXME, or HACK markers. You also get file-level module comments describing each file's responsibility and dependencies within the architecture, @example blocks showing [example_count] usage patterns spanning the happy path, an error case, and an edge case, and @see cross-references linking related functions such as implementations to their interfaces. Every comment is written to satisfy [lint_tool] rules without restating what clear naming already conveys.
Pro tips
- Point
[code_area]at the parts where intent is genuinely unclear, like auth or billing, so the why-comments land where they matter. - Set
[complexity_threshold]to a real value so only non-obvious logic gets inline explanation and simple code stays uncluttered. - List concrete
[failure_scenarios](high concurrency, null inputs, timezone changes) so the TODO/FIXME markers flag real risks. - Keep
[example_count]modest but cover happy path, error case, and edge case — those three teach the most. - Enforce
[lint_tool]so generated docs meet your standards and do not just restate parameter names. - Review the inline comments for accuracy; the AI explains its reading of the code, which you should confirm matches the real intent.
