0xMiden / 0xMiden/tutorials

chore: standardize MASM formatting in tutorial files

Offen Anfängerfreundlich
#190 4 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
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

Beitragsleitfaden öffnen

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

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.