Writing style

The docstrings and docs are read by people who just installed the package and want to get something done. Write for them.

This page is a set of hard rules, not advice. Each one names a habit that keeps showing up in this codebase and gives a mechanical test you can apply to a sentence without a judgment call. If a sentence fails a test, rewrite it or cut it.

The whole page reduces to one instruction: say what the thing is and what the reader does with it, then stop.

The rules

1. Never state the absence of something the reader never expected.

"Pure and pandas-free." "Dependent tasks without a name regex." "No GCP staging." Naming what something isn't only helps when the reader would otherwise assume it is. They wouldn't. It reads as an inside reference to a problem they were never part of.

• Bad: The shared driver is pure and pandas-free.
• Good: The shared driver turns raw scores into one result row.
• Test: the sentence says X is "without / free-of / no / not" Y. Would a first-time reader have assumed Y in the first place? If not, delete the clause.

2. Never end a sentence by explaining why it's clever.

The recurring tic here is a trailing payoff: "…, so prioritization is defined once," "…, so they can't drift," "…, which is the whole win." Every sentence ends by asking the reader to admire the design. State the fact. Let them draw the conclusion.

• Bad: Declare the column once here, so the schema, the validator, and the TSV headers can't drift.
• Good: Declaring the column here sets the schema, the validator, and the TSV headers.
• Test: the sentence ends with "so…", "which means…", "so that…", "the whole point…". Does that clause tell the reader something they need, or does it praise the design? If it praises, cut it.

3. One sentence, one fact.

Stacking three facts into one sentence with dashes, colons, and parentheses looks dense and is hard to read. Split it.

• Bad: Streams one MaterializedVariant per variant (an async generator), so a millions-of-variants job never buffers the whole result: it fetches and merges annotations, then per variant assembles each model's scores.
• Good: Yields one result per variant instead of building the whole list, so a large job stays within memory. For each variant, it merges the annotations and then adds each model's scores.
• Test: count the separate facts in the sentence. More than two? Split it. Count the dashes, colons, and parentheses. More than one? You are probably stacking.

4. Say it in plain words before you name it.

Coined shorthand — "the results-side trio", "type-fenced", "push-down", "backend-neutral" — means nothing to a reader who hasn't seen it defined. Write the plain sentence first. Introduce the shorthand only if it then earns its keep.

• Bad: ModelResults is what materialize is type-fenced to.
• Good: The data layer only ever calls these three methods, so it can't reach the compute methods by accident.
• Test: is there a compound noun or invented phrase the reader has not been shown the meaning of? Replace it with the plain sentence it stands for.

5. Don't use bold or italics to add stress.

Emphasis marks are for a genuine term of art on first use, nothing else. They are not for signaling that a point matters. If a sentence needs bold to land, the sentence is wrong.

• Test: delete every ** and *. Did the meaning change? If not, leave them deleted.

6. Don't editorialize about the code.

"The standout." "Genuinely strong." "The elegant part." "The point isn't X, it's Y." The reader wants to know how the thing works, not how good the author thinks it is. Cut every value judgment about the design.

• Test: is there an adjective praising the code — elegant, clean, powerful, neat, the-real-X? Remove it.

7. Lead with the plain definition.

The first sentence says what the thing is, in words a new colleague would understand. Rationale, history, and edge cases come after — if they come at all.

• Bad: an opening paragraph about two ABCs and which surface a consumer depends on.
• Good: A ModelPlugin describes one model architecture: what its scores look like, and how to produce them.
• Test: read only the first sentence. Does someone who has never seen this class now know what it is?

8. Cut qualifiers and hedges.

"Effectively", "essentially", "in practice", "more or less", "note that", "it's worth noting". They add length and subtract confidence. Say the thing.

• Bad: Note that this is essentially the same object the submit path builds, more or less.
• Good: This is the same object the submit path builds.
• Test: search the sentence for a hedge word. Delete it and check the sentence is still true. It usually is.

Check yourself before committing

Read the docstring out loud as if you were explaining it to a new colleague standing next to you. If a sentence sounds like a brochure, a riddle, or a victory lap, it fails. Rewrite it plainly. When in doubt, cut.