0xMiden / 0xMiden/tutorials

chore: standardize MASM formatting in tutorial files

Abierto
#190 4 comentarios 0 reacciones 0 asignados Ver en GitHub
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

Abrir la guía de contribución

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.