Code Comment Styles: Docstrings vs Inline (Prompt Guide)

A two-person team maintains an open-source TypeScript date library. Six months after launch they get their first outside pull request, and the reviewer’s only blocker is a one-liner: “I cannot tell what addBusinessDays does with holidays, and the function has no docs.” The code is correct. The library just never told anyone why it behaves the way it does, and neither did the prompt that generated it.

When you ask ChatGPT to write code, the comment style you request decides whether the result is a tool someone else can adopt or a puzzle only the author can read. This guide gives a decision table for five comment styles, the situation each one fits, a prompt snippet per style, and the trade-offs. Every example uses the same subject: a TypeScript date utility library exporting functions like addBusinessDays, isLeapYear, and isoWeek. For baseline model setup, see ChatGPT coding settings, and to pair comments with tests, see ChatGPT TDD settings.

Comment Style Decision Table

Two questions pick the row. Who reads this code — only you, or anyone who installs the package? And does the reader need the “what” or the “why”? Doc blocks answer “what” for outsiders. Inline notes answer “why” for future maintainers, who may well be you in six months.

When to Use Each Style

Doc blocks are non-negotiable for public API. Any function a caller imports deserves a doc comment that states purpose, parameters, return value, thrown errors, and one usage example. For a date library, addBusinessDays must say whether it mutates its input and how it treats holidays, because those are the two questions every reviewer asks.

Inline “why” notes are for the lines that look wrong but are not. A hand-written leap-year check, an off-by-one in ISO week calculation, a hardcoded 86400000 — each deserves one sentence explaining the reason, not the mechanics. Resist commenting every line; a file that explains the obvious buries the one line that matters.

Type signatures document contracts for free and let the editor flag mistakes before runtime. A well-typed function returning a branded ISO-week string tells a reader more than a paragraph. Types cannot explain intent, though, so they complement doc blocks rather than replace them.

Section headers help a 600-line file by grouping “parsing”, “arithmetic”, and “formatting” helpers. In a small module they are noise that pushes real content down the screen.

No comment at all is the correct default when the name already says everything. A private helper called daysInMonth does not need a comment; adding one trains readers to skip comments, which is worse than writing none.

Prompt Snippets by Style

Doc block (TSDoc)

Write a TypeScript function addBusinessDays(date: Date, days: number): Date.
Add a TSDoc block above the signature that includes:
- One sentence on what it does.
- @param for each argument, noting that the input Date is not mutated.
- @returns describing the produced Date.
- @throws for the invalid-input case.
- One @example line showing a call and its result.
Then implement it, skipping Saturdays and Sundays. Do not add inline comments inside the body.

Inline “why” note

Review the TypeScript file below. Add an inline comment ONLY where a reader would ask "why", not "what". Good candidates:
- A hand-written leap-year rule.
- A magic number that encodes a unit.
- A branch that looks redundant but handles an edge case.
Rules:
- One short sentence per comment, placed on the line above the code.
- Do not comment self-explanatory lines.
- Do not restate the code in English.
Return the full file with comments added.

Type signature

Refactor the TypeScript date helpers below to make the contracts explicit through types alone.
Requirements:
- Replace loose string parameters with a union of allowed literal values.
- Return a named type instead of a bare string for ISO-week output.
- Mark parameters readonly where the function must not mutate them.
- Remove any comment that only describes what the code does.
Keep behavior identical and show the before and after for each function.

Section header

Organize the TypeScript date module below into three labeled sections in this order: Parsing, Arithmetic, Formatting.
Rules:
- Put one banner comment above each section, using the exact section name.
- Move every exported function into the correct section without changing its code.
- Do not add any other comments inside the functions.
Return the reorganized file.

No comment (self-documenting names)

Rewrite the TypeScript helper below with clear names and no comments.
Rules:
- Rename cryptic variables and one-letter parameters to full words.
- Extract any expression that needs a comment into a named boolean or function.
- Delete every comment that merely narrates the code.
- Keep behavior identical and keep the public function signatures the same.
Return the refactored code.

Trade-Offs

Doc blocks cost tokens and maintenance. Every time a function changes, its example can go stale, and a wrong doc block is worse than none. The mitigation is to generate the example from a real unit test so the two move together. Inline “why” notes are cheap and high-value but easy to overuse; the discipline is to ask whether removing the comment would actually confuse a competent reader. If not, delete it.

Type signatures are free after the first edit and never drift, but they cannot express performance, side effects, or intent, so a library still needs prose for the tricky parts. The reliable mix for a date library is: doc block on every export, inline note only for the algorithmic surprises (leap years, ISO weeks, timezones), full typing everywhere, and no narration. Ask for that shape in one prompt, and ask the model to remove any comment a reviewer could have written after reading the code — those comments add nothing.

Sources & Notes

Prompts tested with ChatGPT on the GPT-4o and GPT-4.1 models in October 2026. TSDoc follows the Microsoft TypeScript documentation standard; JSDoc behavior matches the same conventions. The date library, its functions, and the review comment are an illustrative scenario. No compilers or package registries were called; all prompts are copy-paste text. Category mapping follows the guunn.com AI Prompts plan (Coding = 957).