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:
@@ -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*,
|
||||
|
||||
Reference in New Issue
Block a user