From e11fa22f4a5dec1e52aceff84c196547850d3daf Mon Sep 17 00:00:00 2001 From: Jonathan Springer Date: Wed, 16 Sep 2026 13:49:18 +0100 Subject: [PATCH] docs(agents): add Clean Code, minimal-comments, and ASD-STE100 conventions Codify the maintainer's style policy for agents: code follows Clean Code and carries as few comments as possible (code is its own documentation - comment only what code cannot express); project writing complies with ASD-STE100 Simplified Technical English. Signed-off-by: Jonathan Springer --- AGENTS.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 1150420..0a92e56 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -60,11 +60,26 @@ uses line-length 120, target py311. ## Code conventions +- Coding standards align with Robert C. Martin's *Clean Code*: + intention-revealing names, small functions that do one thing, few + arguments, no duplication, boring control flow over cleverness. +- Keep comments to a minimum - code is its own documentation. Prefer code + that explains itself through names, structure, and tests. Comment only + what code cannot express (for example, a security invariant or a + non-obvious external contract); delete comments that restate the code. - Imports are grouped with the repo's section-comment style (`# Future` / `# Standard` / `# Third-Party` / `# First-Party`); keep it. - Logging goes through `logging_config.py` (`LoggingService` / `CorrelationIdJsonFormatter`), not ad-hoc `logging.getLogger` handlers. +## Writing conventions + +- Project writing (README, USER_README, docs/, and other user-facing + prose) complies with ASD-STE100 Simplified Technical English: use only + approved words, keep sentences short, give one instruction per + sentence, write in the active voice and present tense, use one term + for one concept, and write procedures as numbered steps. + ## Contribution workflow - Open an issue before a PR (bugs and features both). Do not implement