---
name: docstring-and-comment-pass
description: "Reviews code comments and docstrings, adding the ones that explain why a choice was made and removing the ones that only restate what the code says. Use when a source file or function has missing, noisy or stale comments and docstrings and needs them rewritten to explain why rather than what. Do not use for writing project documentation or renaming and restructuring code. Related topics: coding, writing."
---

# Docstring and Comment Pass

Reviews code comments and docstrings, adding the ones that explain why a choice was made and removing the ones that only restate what the code says.

## When to use

Use this skill when a source file or function has missing, noisy or stale comments and docstrings and needs them rewritten to explain why rather than what. Do not use it for writing project documentation or renaming and restructuring code.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. Read the code and mark each spot that is non-obvious: workarounds, business rules, ordering constraints and edge cases.
3. Add comments at those spots that give the reason, including why the obvious alternative was not used.
4. Remove or flag comments that restate the code or are stale, and suggest a rename where a better name replaces the comment.
5. Write docstrings for the public items in the chosen style with purpose, parameters, return value, errors and a brief example.
6. List every place where the reason is unknown and ask the author, leaving code behaviour untouched.

## Inputs

- **Code** (longer free text)
- **Language** (free text, e.g. "Python or TypeScript or Go")
- **Docstring style** (choose one: Google, NumPy, JSDoc, Plain sentences, Match existing)
- **Who reads this code** (free text, e.g. "Teammates or open source users or future me")
- **Public API only** (choose one: Yes, No)
- **Business context** (longer free text)

## Output

The annotated code with unchanged logic, then a list of removed comments with reasons and a list of open questions for the author.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### Docstring and Comment Pass

Improve the comments in this code.

- Code: {{Code}}
- Language: {{Language}}
- Docstring style: {{Docstring style}}
- Who reads this code: {{Who reads this code}}
- Public API only: {{Public API only}}
- Business context: {{Business context}}

Read the code first and decide what is non-obvious: a workaround, a performance trick, a business rule, an ordering constraint, a surprising edge case. Those earn comments that explain why, including the reason an obvious alternative was rejected. Delete or flag comments that restate the next line, are stale, or hide bad naming; suggest the rename instead of a comment where a clearer name would fix it. Write docstrings for the public items in the chosen style, covering purpose, parameters, return value, errors raised and one short example where it helps. If the toggle says public only, leave private helpers alone. Do not change any code behaviour. Return the annotated code, then a short list of removed comments and the reason, and a list of questions where the why is unknown and the author must supply it, rather than inventing a reason.

## Pitfalls

- Inventing a plausible reason for a strange line, which gives future readers false confidence.
- Commenting every line, which buries the few comments that matter.
- Editing code while polishing comments, which hides a behaviour change inside a documentation diff.