Naming Conventions and Deprecation Policy

Rust

• https://rust-lang.github.io/api-guidelines/naming.html
• rust fmt

Hard Rules

Indexed Code

SCALE encoding and a lot of the metadata relies on stable indices. When adding any of the prior, do NOT reorder. ALWAYS add to the end. Those relying on those magic numbers thank you.

• Pallet Indexes
• Events
• Extrinsics
• Argument order

External Interface Stability Required

Remember that more is external than it might appear.

• State Queries
• Constants
• Runtime Calls
• Custom RPCs

Changes MUST follow the deprecation pattern.

Deprecation

Changes will happen and eventual deprecation of something is expected. Any change that alters an external interface MUST follow the following if at all possible.

1. Create a new interface, if necessary, suffix the name(s) with _v2 (or correct integer increment).
2. In Rust, tag the prior interface as #[deprecated = "Use xxxx_v2 instead"]
3. Note in the Changelog the deprecation.
4. Wait at least 6 months.
5. Remove the deprecated interface noting the "Breaking Change" in the Changelog

Suggestions

General Rules of Thumb

• Avoid single words on external interfaces
• Governance managed variables should be prefaced by governance
• Be descriptive
• is/has: Should return a bool

State Storage Values

• Single Maps
  • [map key]To[map value]
  • [map value]For[map key]
• Double Maps
  • [map key]And[map key 2]To[map value]
• N Maps
  • Good Luck

Constants

• [Max/Min][Foo]Per[Bar]

Extrinsics

• Verbs
  • set: Change a value to a new value
  • add: Append to a list of something
  • create: Creating something new that might have other things added to it
  • register: USE create INSTEAD
  • grant/revoke: Permission oriented terms
  • delete: Never about permissions, actually delete something
  • retire: Delete is not right, but neither is revoke (Used for MSAs "removal" only)
• Junctions
  • with
  • by
• Help
  • Foo grants/revokes a permission
  • A delegator creates a delegation with a provider
  • A user creates an MSA and then adds public keys to it.

RPCs

• getBy: pallet_getByFoo
• check: Test a thing and return result
• No need to prefix with get

Events

• Past tense verbs