Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 30 additions & 1 deletion .claude/skills/masm-inline-comments/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
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.:
Expand Down
Loading