From 4a1a9ada394ae43267d20fe2344b8e899570b2c4 Mon Sep 17 00:00:00 2001 From: "Claude (Opus)" Date: Thu, 3 Sep 2026 10:49:19 +0000 Subject: [PATCH 1/2] chore: keep MASM inline comments to what the code does Extends rule 6 of the masm-inline-comments skill: an inline comment is one line about what the next block does or which invariant it relies on, not design rationale, PR-review reasoning, or a justification of step ordering, which belong in the procedure's doc comment. Prompted by review on #3798, where such prose had to be trimmed by hand. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01KkQzFtRjyDwQ7iVtRbsHsn --- .claude/skills/masm-inline-comments/SKILL.md | 31 +++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/.claude/skills/masm-inline-comments/SKILL.md b/.claude/skills/masm-inline-comments/SKILL.md index 9e1a5834d8..82b16696fc 100644 --- a/.claude/skills/masm-inline-comments/SKILL.md +++ b/.claude/skills/masm-inline-comments/SKILL.md @@ -86,10 +86,39 @@ end Use the vocabulary already established in the surrounding code and doc comments. Do not coin new terms or colloquialisms for a concept that already has a name — a value written to a local is "stored", not "stashed". This applies to inline comments and to constant-header comments. -### 6. Comment the code, not the change +### 6. Comment the code, not the change or the design Inline comments explain what the code does for a future reader, not why a particular PR made a change. Avoid PR narrative and framing such as "this is the X that prevents Y"; describe the operation and its purpose as the code stands. +An inline comment states, in one line, what the next instruction block does or which invariant it relies on. It does not: + +- explain why the design is the way it is, or which alternatives were rejected +- restate reasoning from a PR review or from the procedure's `#!` doc comment +- justify the ordering of steps with rationale; that belongs in the doc comment (see masm-doc-comments skill) + +**Avoid (implementation detail and rationale in an inline comment):** + +```masm +# one slot beyond the approvers, for the guardian signature. It is unconditional because the +# rotation path verifies no guardian signature but scans every account procedure instead, which +# the slot also covers. +add.1 + +# settle the sponsorship obligation first, in pay_fee's order; the bound below guards the +# host-supplied rate, which the sponsorship amounts do not depend on +exec.fees::create_network_note_sponsorships drop +``` + +**Good:** + +```masm +# one slot beyond the approvers, for the guardian signature +add.1 + +# settle the sponsorship obligation first +exec.fees::create_network_note_sponsorships drop +``` + ### 7. Accessing a word's individual elements When accessing individual elements of a word, show the word destructured into elements, grouped with brackets, e.g.: From 86585105f980f68e9406887deb492670d825f5db Mon Sep 17 00:00:00 2001 From: Marti Date: Thu, 3 Sep 2026 14:35:28 +0200 Subject: [PATCH 2/2] Apply suggestion from @zeapoz Co-authored-by: zeapoz --- .claude/skills/masm-inline-comments/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.claude/skills/masm-inline-comments/SKILL.md b/.claude/skills/masm-inline-comments/SKILL.md index 82b16696fc..165a09ad14 100644 --- a/.claude/skills/masm-inline-comments/SKILL.md +++ b/.claude/skills/masm-inline-comments/SKILL.md @@ -115,7 +115,7 @@ exec.fees::create_network_note_sponsorships drop # one slot beyond the approvers, for the guardian signature add.1 -# settle the sponsorship obligation first +# settle the sponsorship obligation exec.fees::create_network_note_sponsorships drop ```