writing-comments

Source excerpt starting at line 1.

1---2name: writing-comments3description: How to write JSDoc (/** */) and inline (//) comments in the Astro codebase, for contributors reading the source — not end users. Use whenever writing or editing comments in .ts/.js source, including comments added incidentally while fixing bugs or building features. Does not cover the @docs-generated config/error reference.4---5 6# Writing Comments7 8## Purpose9 10Comments in this repository are read by contributors, months or years after11they were written, with none of the context you have right now. This skill12defines who that reader is, what each kind of comment is for, and which patterns13are banned.14 15## Scope Boundary16 17This skill governs **contributor-facing** comments in the TypeScript/JavaScript18source. It does **not** apply to end-user documentation:19 20- JSDoc blocks tagged `@docs` in21  [`packages/astro/src/types/public/config.ts`](../../../packages/astro/src/types/public/config.ts)22  and23  [`packages/astro/src/core/errors/errors-data.ts`](../../../packages/astro/src/core/errors/errors-data.ts)24  are scraped by an external `docgen` tool and published to the Astro docs25  website. Follow26  [`packages/astro/src/core/errors/README.md`](../../../packages/astro/src/core/errors/README.md)27  for those, and get docs-team review — CI regenerates the reference when28  `types/public/**` changes.29- Other JSDoc across `types/public/**` is surfaced to users through editor30  IntelliSense. Write it for Astro **users** building a site, not for31  contributors reading the source.32 33Everything below is about the source a contributor reads at HEAD.34 35## The Reader36 37Write for an Astro contributor who is competent in TypeScript but has **no38access to your current context**: not this conversation, not the pull request,39not the issue, not the diff. They see only the repository at HEAD.40 41Two consequences follow directly:42 431. **Never narrate change history.** Words like "now", "previously", "no44   longer", "the new approach" are meaningless at HEAD, where only one approach45   exists. State how the code works, not how it came to be. (A `@deprecated`46   notice is the exception — see [Conventions](#conventions-in-this-codebase) —47   because it describes the contract's future, which the reader needs.)482. **Never address the reviewer.** A comment that argues your change is correct49   ("this properly handles X") belongs in the PR description, not in the source.50   The comment must justify the code as it stands, permanently.51 52## Three Kinds of Comments, Three Different Jobs53 54| Kind                   | Syntax                                | Job         | Contains                                                                                          |55| ---------------------- | ------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------- |56| File / module overview | `/** */` at the top of the file       | Explanation | Why the module exists, the concepts and terms it defines, how the pieces relate, design rationale |57| Item docs              | `/** */` directly above a declaration | Reference   | The contract: behavior, parameters, return value, thrown errors, invariants. Neutral and factual  |58| Inline comments        | `//` inside a body                    | Rationale   | Only what the code cannot say: constraints, workarounds (with issue links), non-obvious coupling  |59 60Do not mix the jobs. Implementation details do not belong in the `/** */`61contract — put them as `//` comments inside the body. The contract does not62belong scattered across inline comments — put it on the declaration.63 64## Behavior Documentation65 66When item documentation is warranted, write the contract for a human reader,67not as a translation of the implementation. This does not require JSDoc for68every function; names, types, and structure should carry straightforward69behavior on their own.70 71- Start with a plain-language description of what the function returns or72  accomplishes.73- Use short or medium-length sentences with one main idea each.74- Avoid internal Astro jargon when callers do not need it. If a technical term75  is necessary, explain it in the same paragraph.76- Describe caller-visible caveats that can be surprising: fallback behavior,77  work limits, ambiguous results, overload ordering, side effects, and the78  conditions that return `undefined`, `null`, an empty result, or another79  indeterminate value.80- Document thrown errors when callers are expected to distinguish or recover81  from them.82- Do not describe implementation details unless callers need them to understand83  the behavior or use the API safely.84 85Add an example when behavior depends on a relationship the signature cannot86show clearly. Common Astro and TypeScript cases include:87 88- which overload is selected;89- how arguments map to optional or rest parameters;90- which public Astro entrypoint exposes a symbol that is implemented or91  re-exported elsewhere;92- fallback behavior for ambiguous routes, incomplete configuration, or missing93  content;94- a result whose meaning is not obvious from its type.95 96Introduce the example in prose before the code block. State what it demonstrates97and what result is expected. Keep snippets minimal, self-contained, and written98from the perspective of an Astro user or the internal caller that owns the99contract.100 101Module documentation should describe a durable concept, architectural boundary,102or design reason. Do not list individual exports merely to summarize the file;103such inventories become stale as symbols are added or renamed. If a module has104no durable concept to explain, use a brief one-line description or no overview.105 106## The Deletion Test107 108Before writing any comment, ask: **does this state something the reader cannot109recover from the code itself?**110 111- If the information is already carried by names, types, or structure, do not112  write the comment. If the name fails to carry it, improve the name.113- Information that legitimately needs a comment: an invariant, a rationale, a114  coupling to code elsewhere, a workaround with a link, surprising behavior of a115  dependency, a term of art the module defines.116 117When editing later, the same test applies in reverse: a comment that no longer118passes it should be deleted, not left to rot.119 120## Link to the Issue for Workarounds121 122This codebase consistently anchors workarounds to a source. Any comment that123explains a workaround, a `HACK`, a regression guard, or surprising behavior of a124dependency **must link the GitHub issue or PR** that motivates it. The link is125what lets a future reader tell whether the workaround is still needed.126 127```ts128// Handle recommended nanostores. Only @nanostores/preact is required from our testing!129// Full explanation and related bug report: https://github.com/withastro/astro/pull/3667130'@nanostores/preact',131```132 133A workaround with no link is indistinguishable from a mistake.134 135## Banned Patterns136 137**Narrating the next line.** Delete these on sight:138 139```ts140// Increment the generation counter141generation += 1;142```143 144**Change-history narration.** Rewrite as present-tense rationale:145 146```ts147// BAD: We now resolve lightningcss from the user's root instead of ours.148// GOOD: lightningcss is an optional peer dep, so it resolves from the user's project root.149```150 151**Reviewer-addressed justification.** Move the argument to the PR:152 153```ts154// BAD: This correctly handles the multi-encoded path from the bug report.155// GOOD: A path still encoded after MAX_DECODE_ITERATIONS is rejected, so156//       middleware and routing can never disagree on the decoded path.157```158 159**Restated JSDoc.** A `/** */` block that rewords the declaration name says nothing:160 161```ts162// BAD:163/** Compiles the styles. */164function compileStyles(...)165 166// GOOD:167/** Rewrites relative `url()` references in `css` against `base`, leaving168 *  absolute and data URLs untouched. */169function compileStyles(...)170```171 172**Vague hedging.** "Some cases", "various reasons", "handles edge cases",173"etc." — either name them or drop the sentence.174 175**Emojis.** Banned in source, comments included (repo-wide policy).176 177**Ad-hoc section banners** (`// ----- helpers -----`, `// ==== TYPES ====`).178This codebase has no `// #region` folding convention; do not add banners. If a179file is long enough that you reach for one, that is a signal to split the file,180not to decorate it.181 182## Conventions in This Codebase183 184**JSDoc tags.** `@param name - description`, `@returns`, and `@throws` state the185contract. Brace-wrap a type (`@returns {Promise<string>}`) only when the186signature alone is ambiguous. Use `@example` with a fenced ` ```js ` block for187non-obvious usage.188 189**Cross-references.** Use `{@link Symbol}` / `{@linkcode Symbol}` rather than a190bare name, so a rename updates the reference and editors can jump to the target.191 192**`@internal`.** Marks API that is not part of the public surface. It is a193convention only — there is no typedoc or api-extractor here to strip it — so it194documents intent but does not replace access modifiers.195 196**`@deprecated`.** State the migration, then the removal horizon:197 198```ts199/** @deprecated Use the instance method `cookies.consume()` instead. This will be removed in Astro 7 */200```201 202Say what to use instead, not merely that the symbol is deprecated. This203future-tense note is contract information the reader needs, not banned204change-history narration.205 206**TODO.** Use `// TODO:` for deferred work; link an issue when one tracks it.207For work gated on a breaking-change window, use the established idiom208`// TODO: remove in Astro <N>`. There is no `FIXME` in this codebase — do not209introduce it.210 211## Editing Existing Code212 213- Preserve existing comments. If your change alters behavior, extend or correct214  the specific prose — never replace it with generic text. Deleting hard-won215  context is worse than leaving a comment slightly stale.216- When your change makes a comment false, fix it in the same diff. A stale217  comment is worse than none.218- Match the surrounding density. A heavily documented module deserves the same219  level on new items; do not blanket a sparse module with comments.220 221## Self-Check Before Finishing222 223After completing any task that touched comments, re-read **only the comments in224your diff**, in isolation from the code changes:225 2261. Does each one pass the deletion test?2272. Does any reference the conversation, the change itself, or the reviewer?2283. Does every workaround link its issue or PR?2294. Would a reader without access to the diff understand each one?230 231Fix or delete what fails. Deletion is the default; a missing comment is cheaper232than a misleading one.233 234## References235 236- [Diátaxis](https://diataxis.fr/) — the framework behind the explanation /237  reference / rationale split above.238- [`packages/astro/src/core/errors/README.md`](../../../packages/astro/src/core/errors/README.md)239  — for `@docs`-tagged error entries, which are end-user documentation.240- [TSDoc](https://tsdoc.org/) — the tag reference for TypeScript doc comments.241