chore: standardize MASM formatting in tutorial files
- Vorherrschende Sprache
- Rust
- Sterne
- 18
- Forks
- 34
- PR-Merge-Kennzahlen
- Keine gemergten PRs in 30 T.
Beschreibung
## Context
During the v0.14 migration review ([tutorials#186](https://github.com/0xMiden/tutorials/pull/186)), @partylikeits1983 flagged that MASM stack comments and formatting across the tutorial files don't consistently follow the conventions used in `miden-protocol` and `miden-vm`. This creates friction for pioneers who submit code after following our tutorials for review, since the style is "way off" from what core maintainers expect.
## Scope
Standardize MASM formatting across all MASM in the tutorials repository:
- `masm/accounts/*.masm` (counter, count_reader, oracle_reader, mapping_example_contract)
- `masm/accounts/auth/*.masm` (no_auth)
- `masm/notes/*.masm` (network_increment_note, hash_preimage_note, iterative_output_note)
- `masm/scripts/*.masm` (counter_script, reader_script, oracle_reader_script, mapping_example_script)
- `web-client/lib/masm/*.masm` (counter_contract, count_reader)
- Inline MASM code blocks in `docs/src/**/*.md` tutorial files
## Conventions to apply
Follow the conventions used in `0xMiden/miden-base` (see `crates/miden-protocol/asm/`) and `0xMiden/miden-vm` (see `stdlib/asm/`):
- Doc comments (`#!`) with Description, Inputs, Outputs, Where, Panics if, Invocation sections
- Capitalization: UPPERCASE for Word-sized values (`ASSET`, `RECIPIENT`, `FOREIGN_PROC_ROOT`), lowercase for single felts (`amount`, `count`), lowercase with `{parts}` suffix for multi-felt composites (`account_id_{prefix,suffix}`)
- Inline stack comments start with lowercase and only annotate non-obvious state
- Stack state after non-obvious operations: `# => [ITEM, felt, ...]`
- Padding notation: explicit `pad(N)` for `call` procedures, no padding notation for `exec` procedures
- Left-to-right stack order (top of stack first)
## References
- Alex's inline suggestion on [tutorials#186](https://github.com/0xMiden/tutorials/pull/186) for `count_reader.masm`
- Existing MASM skills in `0xMiden/agent-skills`: `masm-inline-comments`, `masm-doc-comments`, `masm-padding`
- Companion issue in agent-skills for the new formatting skill: [agent-skills#6](https://github.com/0xMiden/agent-skills/issues/6)
## Acceptance
- [ ] All public procedures have `#!` doc comment blocks with required sections
- [ ] Stack notation follows capitalization rules consistently
- [ ] Padding notation is correct for each procedure's invocation type
- [ ] Inline comments start lowercase and only annotate non-obvious state
- [ ] All files reviewed against the new MASM formatting skill once available ([agent-skills#6](https://github.com/0xMiden/agent-skills/issues/6))
Beitragsleitfaden
Rechercherichtung
The issue lists specific MASM files in masm/accounts/, masm/notes/, masm/scripts/, and web-client/lib/masm/, plus inline code in docs/src/**/*.md. Start by examining the referenced conventions in the miden-base and miden-vm repositories (crates/miden-protocol/asm/, stdlib/asm/). Compare a tutorial file like masm/accounts/counter.masm to the style guide, then apply the formatting rules for doc comments, capitalization, stack comments, and padding. Run any existing tests or lints to verify changes.
Vom Indexierungsmodell aus dem Issue-Text verfasst.
Bewertung
- Bereich
- documentation
- Issue-Typ
- Dokumentation
- Schwierigkeit
- 2/5
- Geschätzter Aufwand
- 1-3 Stunden
- Aktivitätsstatus
- Ruhig
- Klarheit
- Klar beschrieben
- Anfängerfreundlichkeit
- 65/100