refine(pseudo): comment economy — own-line, only when not self-explanatory

Add rule 2: comment only what the code cannot say itself;
self-explanatory pseudocode needs none. Put any comment on its
own line above the code; reserve trailing end-of-line comments
for the briefest notes (a bare marker, one or two words), since a
column of trailing prose scans worse than a short note above.

Rework rule 4 (markers) so the bare marker rides trailing while
any explanation it needs moves to an own line. Renumber the rule
list (now 1-10) and fix the mechanics->reduce cross-reference.
Iron Law, worked example, frontmatter, and README updated to
match; the example now demonstrates the sparse-comment style.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-06-04 12:59:29 +02:00
parent 38fe94d3ac
commit 03eeb0c672
2 changed files with 88 additions and 54 deletions
+6 -3
View File
@@ -39,9 +39,12 @@ with a source-file-and-line anchor, marks notable steps with
reference markers the user can point back at, sketches the
layout of the data structures the code touches alongside the
flow, reduces the irrelevant to stubs, and omits low-level
mechanics. Prose is allowed only in a supporting role — the
pseudocode block stays the centre of every answer. It dispatches
no agents.
mechanics. The pseudocode leans on the source language's idiom
in a language-tagged fence so it renders with syntax
highlighting, and keeps comments sparse — on their own line and
only where the code is not self-explanatory. Prose is allowed
only in a supporting role — the pseudocode block stays the
centre of every answer. It dispatches no agents.
Vocabulary is configurable. A **cycle** is one round in the
pipeline graph; your project may call it a *release*, an *epic*,