Comments in this repository are read by contributors, months or years after\nthey were written, with none of the context you have right now. This skill\ndefines who that reader is, what each kind of comment is for, and which patterns\nare banned.
\nThis skill governs contributor-facing comments in the TypeScript/JavaScript\nsource. It does not apply to end-user documentation:
\n@docs in\npackages/astro/src/types/public/config.ts\nand\npackages/astro/src/core/errors/errors-data.ts\nare scraped by an external docgen tool and published to the Astro docs\nwebsite. Follow\npackages/astro/src/core/errors/README.md\nfor those, and get docs-team review — CI regenerates the reference when\ntypes/public/** changes.types/public/** is surfaced to users through editor\nIntelliSense. Write it for Astro users building a site, not for\ncontributors reading the source.Everything below is about the source a contributor reads at HEAD.
\nWrite for an Astro contributor who is competent in TypeScript but has no\naccess to your current context: not this conversation, not the pull request,\nnot the issue, not the diff. They see only the repository at HEAD.
\nTwo consequences follow directly:
\n@deprecated\nnotice is the exception — see Conventions —\nbecause it describes the contract's future, which the reader needs.)| Kind | \nSyntax | \nJob | \nContains | \n
|---|---|---|---|
| File / module overview | \n/** */ at the top of the file | \nExplanation | \nWhy the module exists, the concepts and terms it defines, how the pieces relate, design rationale | \n
| Item docs | \n/** */ directly above a declaration | \nReference | \nThe contract: behavior, parameters, return value, thrown errors, invariants. Neutral and factual | \n
| Inline comments | \n// inside a body | \nRationale | \nOnly what the code cannot say: constraints, workarounds (with issue links), non-obvious coupling | \n
Do not mix the jobs. Implementation details do not belong in the /** */\ncontract — put them as // comments inside the body. The contract does not\nbelong scattered across inline comments — put it on the declaration.
Before writing any comment, ask: does this state something the reader cannot\nrecover from the code itself?
\nWhen editing later, the same test applies in reverse: a comment that no longer\npasses it should be deleted, not left to rot.
\nThis codebase consistently anchors workarounds to a source. Any comment that\nexplains a workaround, a HACK, a regression guard, or surprising behavior of a\ndependency must link the GitHub issue or PR that motivates it. The link is\nwhat lets a future reader tell whether the workaround is still needed.
// Handle recommended nanostores. Only @nanostores/preact is required from our testing!\n// Full explanation and related bug report: https://github.com/withastro/astro/pull/3667\n'@nanostores/preact',\nA workaround with no link is indistinguishable from a mistake.
\nNarrating the next line. Delete these on sight:
\n// Increment the generation counter\ngeneration += 1;\nChange-history narration. Rewrite as present-tense rationale:
\n// BAD: We now resolve lightningcss from the user's root instead of ours.\n// GOOD: lightningcss is an optional peer dep, so it resolves from the user's project root.\nReviewer-addressed justification. Move the argument to the PR:
\n// BAD: This correctly handles the multi-encoded path from the bug report.\n// GOOD: A path still encoded after MAX_DECODE_ITERATIONS is rejected, so\n// middleware and routing can never disagree on the decoded path.\nRestated JSDoc. A /** */ block that rewords the declaration name says nothing:
// BAD:\n/** Compiles the styles. */\nfunction compileStyles(...)\n\n// GOOD:\n/** Rewrites relative `url()` references in `css` against `base`, leaving\n * absolute and data URLs untouched. */\nfunction compileStyles(...)\nVague hedging. \"Some cases\", \"various reasons\", \"handles edge cases\",\n\"etc.\" — either name them or drop the sentence.
\nEmojis. Banned in source, comments included (repo-wide policy).
\nAd-hoc section banners (// ----- helpers -----, // ==== TYPES ====).\nThis codebase has no // #region folding convention; do not add banners. If a\nfile is long enough that you reach for one, that is a signal to split the file,\nnot to decorate it.
JSDoc tags. @param name - description, @returns, and @throws state the\ncontract. Brace-wrap a type (@returns {Promise<string>}) only when the\nsignature alone is ambiguous. Use @example with a fenced ```js block for\nnon-obvious usage.
Cross-references. Use {@link Symbol} / {@linkcode Symbol} rather than a\nbare name, so a rename updates the reference and editors can jump to the target.
@internal. Marks API that is not part of the public surface. It is a\nconvention only — there is no typedoc or api-extractor here to strip it — so it\ndocuments intent but does not replace access modifiers.
@deprecated. State the migration, then the removal horizon:
/** @deprecated Use the instance method `cookies.consume()` instead. This will be removed in Astro 7 */\nSay what to use instead, not merely that the symbol is deprecated. This\nfuture-tense note is contract information the reader needs, not banned\nchange-history narration.
\nTODO. Use // TODO: for deferred work; link an issue when one tracks it.\nFor work gated on a breaking-change window, use the established idiom\n// TODO: remove in Astro <N>. There is no FIXME in this codebase — do not\nintroduce it.
After completing any task that touched comments, re-read only the comments in\nyour diff, in isolation from the code changes:
\nFix or delete what fails. Deletion is the default; a missing comment is cheaper\nthan a misleading one.
\npackages/astro/src/core/errors/README.md\n— for @docs-tagged error entries, which are end-user documentation.