chore: standardize MASM formatting in tutorial files
- Lenguaje dominante
- Rust
- Estrellas
- 18
- Forks
- 34
- Métricas de merge de PR
- Sin PR fusionados en 30 d
Descripción
## 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))
Guía de contribución
Evaluación
Este issue todavía no se ha evaluado.