Purpose

Rust syntax does not determine a comment's audience. Some comments explain the implementation to Biome contributors. Others are published for Biome users or client authors. Before editing a comment, trace where it is consumed by checking nearby derives, attributes, macros, generators, generated artifacts, and help snapshots.

Identify the Audience

A file can mix audiences. For example, workspace.rs contains contributor-facing module docs and user-facing daemon contracts, while FormatterConfiguration has user-facing field docs and contributor-facing methods.

A comment can also feed multiple destinations. Write for the least specialized reader, use only formatting supported by every destination, and inspect the rendered output. Neither /// nor pub proves who the reader is; follow the text to its destination.

Contributor reader

Write for a contributor who knows Rust but has no access to this conversation, the pull request, the issue, or the diff. Describe the code at HEAD. Never narrate change history or address a reviewer.

End-user reader

Write for an intelligent adult who may be using Biome or the documented feature for the first time. Do not require knowledge of Rust, Biome internals, advanced knowledge of the target language's idioms or terminology, or unstated ecosystem concepts.

Use an ELI18 register: beginner-friendly, technically complete, and never childish. Prefer the most familiar accurate term. In JavaScript documentation, for example, prefer variable to binding when both are correct. If the distinction matters, define it on first use: "a binding (a name introduced by code, such as a variable, parameter, or import)." Do not assume client authors know Biome's Rust implementation.

Follow the Biome philosophy:

• reduce jargon, including target-language idioms, and define necessary terms;
• set clear expectations by stating relevant defaults, prerequisites, effects, limitations, fallback behavior, and error recovery;
• be specific, inclusive, and neutral; avoid vague phrases, idioms, and assumptions about the reader;
• keep CLI text understandable without color or other visual styling.

Use public names, such as files.includes, --write, or openFile, with the spelling shown in the destination. Do not leak a Rust identifier merely because it is convenient for the implementation.

Comment Kinds and Value

Ask what the intended reader can recover from the surface they see. Contributors can inspect names, types, and control flow; improve the code or delete comments that only restate them. End users may see only a help entry, editor hover, generated API, or rule page, so retain the self-contained behavior summary even when the Rust name appears descriptive. Keep item contracts in ///; put implementation rationale beside the code as //, not in user-facing docs.

Writing End-User Documentation

Start with a short, plain-language sentence that says what the item does. Add only relevant details: when to use it, prerequisites, accepted values and units, default or omission behavior, interactions, side effects, persistence, results, limitations, failures, and recovery. Use an example when prose leaves the result ambiguous.

Write in the present tense and active voice, with one main idea per sentence. Use familiar, concrete words; explain necessary terms in the same paragraph. Avoid vague pronouns, unexplained acronyms, idioms, and dismissive words such as "obviously", "simply", or "just". Proofread grammar and terminology.

Use the reader's interface in examples: configuration snippets, shell commands, or the public binding or wire format, not Rust for a non-Rust surface. Introduce what each example demonstrates and its expected result.

Writing Contributor Documentation

Write documentation for a human reader, not as a translation of the implementation.

• Start with a plain-language description of what the function returns or accomplishes.
• Use short or medium-length sentences. Keep one main idea per sentence.
• Avoid internal jargon. If a technical term is necessary, explain what it means in the same paragraph.
• Describe business-logic caveats that can surprise callers. Examples include fallback behavior, work limits, ambiguous results, overload ordering, and conditions that return None, Unknown, or an indeterminate result.
• Do not describe implementation details unless callers need them to understand the behavior.

Add an example when the signature cannot clearly show a relationship such as overload selection, argument mapping, import traversal, fallback behavior, or an otherwise ambiguous result. Introduce what the example demonstrates and its expected result. Keep it minimal and self-contained.

Module docs should describe a durable concept or design reason, not list items that will become stale. If there is no durable concept to explain, use a brief one-line description.

Banned Patterns

Narrating the next line. Delete these on sight:

// Increment the generation counter
generation += 1;

Change-history narration. Rewrite as present-tense rationale:

// BAD: We now intern types instead of cloning them.
// GOOD: Interning avoids cloning these types on every lookup.

Reviewer-addressed justification. Move the argument to the pull request:

// BAD: This correctly handles the overload case from the bug report.
// GOOD: Overloads are matched by arity before parameter types, so a
//       partial-arity call cannot select the wrong candidate.

Restated contributor rustdoc. A doc comment that only rewords the item name adds nothing for a contributor:

// BAD:
/// Handles type inference.
fn infer_types(...)

// GOOD:
/// Infers the type of `expr` in `module`, returning `TypeData::Unknown`
/// when the expression references an unresolved import.
fn infer_types(...)

A self-contained summary can still be necessary in CLI help or an editor hover.

Implementation language in end-user documentation. Describe public behavior, not its Rust representation:

// BAD:
/// Stores an `Option<IndentStyle>` consumed by the formatter.

// GOOD:
/// Uses tabs or spaces for indentation. Defaults to tabs.

Replace phrases such as "returns Some", "sets this enum variant", or "the struct contains" with the result the user observes.

Vague hedging. Name the cases and reasons or remove the sentence. Avoid "some cases", "various reasons", "handles edge cases", and "etc."

Ad-hoc section banners (// ----- helpers -----, // ==== TYPES ====). Use the region comment pattern below instead.

Region Comments

Long files group related items with paired region markers:

// #region FILE-LEVEL METHODS
...
// #endregion

This is an established convention across the codebase (biome_service, biome_module_graph, biome_rowan, the parsers). The Workspace trait in crates/biome_service/src/workspace.rs uses it to group its methods. Editors fold on these markers; they exist for navigation, not documentation.

• Pair every // #region with // #endregion.
• Name what the group contains. Use a plain label, or anchor the name to a function when the region holds one entry point and its private support code.
• Use regions only when folding helps in a long file, impl, or trait block.
• Never use a region name instead of rustdoc on its items.

Editing Existing Code

• Edit the source comment, not a generated schema, binding, or help snapshot.
• Preserve accurate details. If behavior changes, correct the specific prose instead of replacing it with generic text.
• Match nearby density and terminology only for the same audience and destination.
• Keep the change focused; do not rewrite unrelated comments to impose a voice.

Self-Check Before Finishing

Read only the comments in the diff, without the implementation:

1. Identify the reader and every destination.
2. Make each comment understandable without the conversation, change history, reviewer, issue, or diff. Keep issue links only as supplemental context for constraints or tracked workarounds.
3. Delete contributor comments recoverable from the code.
4. Ensure end-user comments stand alone without Rust, Biome-internal, or advanced target-language knowledge and state the details needed to predict behavior.
5. Check public names, examples, terminology, inclusivity, and grammar.
6. Inspect generated or rendered output when applicable.

Delete redundant contributor comments, but retain descriptions required by a user-facing surface.

References

• Biome philosophy — principles for user communication.
• Diátaxis — explanation, reference, and rationale.
• lint-rule-development — lint and assist documentation requirements.