From 15c1df20d726d771999bdfcbafbd36ea7d89283b Mon Sep 17 00:00:00 2001 From: Jean-Pierre Martineau Date: Tue, 6 Oct 2026 21:45:47 -0400 Subject: [PATCH] The style guide states the rule for tool comments and quoted labels The tool part of a tool comment stays exactly as it is, and the explanation after it is prose in STE. A quoted UX label is in code font or in quotation marks, not in italics. Co-Authored-By: Claude Opus 5.5 (1M context) --- docs/development/writing-style.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/development/writing-style.md b/docs/development/writing-style.md index e29f863..06c2209 100644 --- a/docs/development/writing-style.md +++ b/docs/development/writing-style.md @@ -147,8 +147,11 @@ Use a bend only when it helps the reader. In all other cases, use the STE rule. - A comment that explains is written in STE sentences. A short comment can be a phrase ("Clamp at both ends."). -- Keep the tool comments exactly as they are: `noqa`, `type: ignore`, `pragma`, `fmt:`, - and the SPDX line. +- Keep the tool part of a tool comment exactly as it is: `noqa: BLE001`, + `type: ignore[attr-defined]`, `pragma: no cover`, `fmt: off`, and the SPDX line. The + explanation after the tool part is prose: write it in STE + (`# noqa: BLE001 - an optional read. Its absence is acceptable.`). +- Write a quoted UX label in code font or in double quotation marks, never in italics. - Keep the `#:` mark of an attribute comment. Write its text in STE. - Keep the layout of a diagram, a table, or an example in a comment. Change only its words.