starkware-libs Concise comments
Yoni-Starkware's review preferences. Applies when writing, editing, or reviewing comments, doc-comments, module/file docs, or constants — any language (examples are Cairo/TS).
Rule of thumb: keep it short, describe the present, don't narrate history.
Rules
Present, not history. No "old / used to / removed / retired".
- BAD:
// The old claim path that used to live here was REMOVED. - GOOD:
// Forwards a pool withdrawal to CCTP.
- BAD:
No design-doc references. Don't cite plans/specs in code.
- BAD:
// Attaches the forwarding hook. bridge-plan.md #9. - GOOD:
// Attaches the forwarding hook so Circle submits the mint.
- BAD:
Don't re-document external interfaces. Link to theirs.
- BAD:
/// Same as deposit_for_burn but appends hook_data... panics if empty. - GOOD:
/// See TokenMessengerV2::deposit_for_burn_with_hook.
- BAD:
No duplicated docs. Document once — not on both trait decl and impl.
Entry files hold only module declarations. Move types/impls out of
lib.cairo/index.ts/mod.rs; leavemod/re-export lists.Short per-field comments, not struct-level essays.
- GOOD:
// Destination chain (e.g. Ethereum, Polygon).above the field.
- GOOD:
Constants: state the meaning AND the alternative.
- BAD:
/// Permissionless mint. const CALLER: u256 = 0; - GOOD:
/// 0 = anyone may submit the mint; nonzero restricts to that caller.
- BAD:
Names reflect content (files, modules, dirs); group error constants in their own
errorsfile.Enforce in CI, not in review nags:
scarb fmt, prettier, eslint.