| name | doc-comments |
| description | How to write inline comments, rustdoc, and module documentation in the Biome codebase. The audience is Biome developers reading the source, not end users. Use whenever writing or editing `//` comments, `///` item docs, or `//!` module docs — including comments added incidentally while fixing bugs or implementing features. |
| compatibility | Designed for coding agents working on the Biome codebase (github.com/biomejs/biome). |
Purpose
Comments and doc comments in this repository are read by contributors, months
or years after they were written, with none of the context you have right now.
This skill defines who that reader is, what each kind of comment is for, and
which patterns are banned.
Scope boundary: rustdoc inside declare_lint_rule! / declare_assist_rule!
blocks is end-user documentation — it is generated into the website. This skill
does not apply there; see lint-rule-development.
The Reader
Write for a Biome contributor who is competent in Rust but has no access to
your current context: not this conversation, not the pull request, not the
issue, not the diff. They see only the repository at HEAD.
Two consequences follow directly:
- Never narrate change history. Words like "now", "previously",
"no longer", "the new approach" are meaningless at HEAD, where only one
approach exists. State how the code works, not how it came to be.
- Never address the reviewer. A comment that argues your change is
correct ("this properly handles X") belongs in the PR description, not in
the source. The comment must justify the code as it stands, permanently.
Three Kinds of Documentation, Three Different Jobs
