english-prose-style

English prose style

Conventions for written English that will be read by humans: docs, javadoc, commit messages, PR descriptions, identifier names. These rules target the mechanical drift patterns LLMs fall into when writing technical prose. They are deliberately scoped to genuine LLM failure modes; basic grammar (subject-verb agreement, possessives, capitalisation, punctuation spacing) is assumed and not repeated here.

When to apply

Apply these rules when producing:

• Documentation (Markdown, Asciidoc, plain text)
• README files, CHANGELOG entries, release notes
• Javadoc, KDoc, docstrings, inline code comments
• Commit messages, PR titles, PR descriptions, review replies
• Design docs, RFCs, architecture notes
• English identifier names (method, variable, class, file, package)
• Error messages and user-facing log strings

Do not apply for casual chat replies to the user, or for content the user explicitly marked as draft / informal.

Dialect

Default to British English unless the project specifies otherwise (check the project CLAUDE.md or repository conventions). Common project signals: existing prose using behaviour / organisation / colour (British) vs behavior / organization / color (American). Match the existing dialect rather than overriding it.

LLMs tend to drift towards American spelling in long technical documents because the American corpus dominates training data. On edits longer than a few paragraphs, re-read the output and check for consistency before finishing.

Em-dash usage

Em-dash (—) is the single most-flagged issue in LLM-generated technical prose. The rules below are strict.

• No em-dash in section headings. Use a colon: ## reWriteBatchedInserts=true: batch INSERT throughput. If the qualifier does not fit a colon cleanly, move it into the intro sentence below the heading.
• No em-dash in definition lists. Patterns like **Term** — definition (status labels, glossary entries, bullet annotations) should be **Term**: definition.
• No paired em-dashes for parentheticals. X — qualifier — Y becomes X (qualifier), Y, X, qualifier, Y, or two separate sentences.
• No em-dash as a paragraph-level connector. We value backward compatibility — upgrading is... should be a period (We value backward compatibility. Upgrading is...), a semicolon, or a colon depending on the relationship between the two clauses.
• No em-dash to introduce a list. Use a colon: bounded by its own timeout: TCP handshake, optional TLS upgrade, ... (not ... by its own timeout — TCP handshake, ...).
• Use commas for short asides. "The driver, by default, opens one socket" needs no dash.
• Reserve the em-dash for genuine sharp emphasis where comma, colon, semicolon, period, and parentheses would all lose the break. Even then, aim for at most one per page.