ChatGPT Prompts for Code Comments: Documentation That Adds Value
ChatGPT prompts for writing code comments and documentation. Inline comments, JSDoc/docstrings, and README sections that help future developers.
The Prompt
Act as a senior engineer who is known for writing exceptionally clear code documentation.
Write documentation for:
Code: [PASTE FUNCTION/CLASS/MODULE]
Language: {language — affects docstring format}
Docstring format: {JSDoc / Google / NumPy / reStructuredText / plain}
Audience: {junior engineers / mid-level / senior / external API consumers}
Documentation level: {inline comments only / function/class docstrings / full module documentation}
Output:
1. Function/class docstring (complete — includes description, parameters, return value, raises, example)
2. Inline comments (for complex logic only — added to the code with comments, not as a list)
3. Module-level documentation (if documenting a full file — purpose, usage, dependencies, author notes)
4. README section (if this is a public API — installation + quickstart code example)
5. What NOT to comment (identify any redundant or obvious comments in the original code)
Comment quality rules:
- Comments explain WHY, not WHAT (the code shows what it does — comments explain why it does it)
- No comments that merely translate code to English ("increment i by 1" over i++)
- Complex algorithms get a reference to the algorithm name or source
- TODO comments must include: who, what, and by when (or a ticket reference)
- Docstrings must include at least one working code example
Constraints:
- Do not add comments to self-explanatory code — over-commenting reduces readability
- Every parameter in a docstring must include its type and constraints (e.g. must be > 0)
- Code examples in docstrings must be runnable, not pseudocode
- Identify and flag any areas of the code where behavior is non-obvious and documentation is critical
Variables to fill in
-
{code}The function, class, or module to document -
{docstring format}JSDoc, Google, NumPy, reStructuredText, or plain -
{audience}Who will read this documentation — affects technical depth -
{documentation level}Inline comments, docstrings, or full module documentation
How to use this prompt
- Paste legacy code into this prompt to retrofit documentation before a refactoring sprint
- Run this on any public API function before merging to main
- Use the 'what NOT to comment' section to clean up over-commented legacy code
- Have new team members add docstrings to code they just shipped — forces deep reading of what they wrote
Good comments explain why, not what
The most common bad comment is one that translates code to English: // increment the counter above count++. This adds noise without adding information — anyone who can read the code already knows what it does. The comment that adds value is the one that explains why: // Counter must be incremented before the callback fires to prevent race condition in IE11.
Docstrings are your API’s user manual
For any function that other developers will call — especially public APIs — the docstring is the first (and often only) documentation a developer reads. A complete docstring that includes parameter types, return value, raises, and a working example eliminates the most common integration questions before they become support tickets.
Over-commenting is its own form of technical debt
Codebases with comments on every line become harder to read, not easier. When code changes but comments don’t get updated — which is always — you end up with misleading documentation that actively misleads readers. The prompt’s ‘what NOT to comment’ section specifically identifies obvious comments to remove, keeping the documentation signal-to-noise ratio high.
Related free tools
- Free AI Prompt Generator — build structured prompts instantly
- AI Token Counter — estimate API costs before long runs
- AI ROI Calculator — measure AI’s impact on developer productivity