0xMiden / 0xMiden/tutorials

chore: standardize MASM formatting in tutorial files

Ouverte
#190 4 commentaires 0 réactions 0 personnes assignées Voir sur GitHub
Langage dominant
Rust
Étoiles
18
Forks
34
Métriques de merge des PR
Aucune PR mergée en 30 j

Description

## 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))

Guide de contribution

Ouvrir le guide de contribution

Évaluation

Cette issue n'a pas encore été évaluée.

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.