Coding Conventions

Item Order in Rust Modules

Items SHOULD appear in Rust modules in the following order, based on the one used by rust-analyzer:

  1. Inner doc comment
  2. Inner attributes
  3. Unconditional—i.e., not feature-gated—bodyless modules
  4. Conditional—i.e., feature-gated—bodyless modules
  5. Unconditional imports from the following:
    1. std/alloc/core
    2. External crates (including crates from the same workspace)
    3. Current crate, paths prefixed by crate
    4. Current module, paths prefixed by self
    5. Super module, paths prefixed by super
    6. Re-exports—i.e., pub imports not used in the module
  6. Conditional imports from the same
  7. Const items
  8. Static items
  9. Other items

TODO: type aliases before other items?

TODO: how to organize type definitions w.r.t. related logic?

Imports

Imports from the same crate with the same visibility MUST be merged into a single use statement.

Imports from Re-exports

When using whole-crate re-exports from ariel_os::reexports, two imports SHOULD be used: one to bring the re-exported crate into the scope, and the other one to import the required items from that crate, as it it were a direct dependency of the crate, as follows:

#![allow(unused)]
fn main() {
use ariel_os::reexports::embassy_usb;
use embassy_usb::class::hid::HidReaderWriter;
}

Comments

Doc Comments

All public items listed in the documentation—i.e., not marked with #[doc(hidden)]—SHOULD be documented.

Doc comments MUST use the line comment style, not the block style.

Doc comments MUST be written in third person present, not in the imperative mood, as recommended by RFC 1574. Each sentence in doc comments—including the first one, before an empty line—SHOULD end with a period. For instance, instead of:

#![allow(unused)]
fn main() {
/// Get the underlying value
}

write:

#![allow(unused)]
fn main() {
/// Returns the underlying value.
}

More generally, use the std docs as inspiration.

When possible—i.e., when items are in scope—items mentioned in the documentation MUST be linked to (see C-LINK). This is useful for readers, to quickly access the mentioned item, but it also helps prevent the docs from lagging behind, as broken links are tested for in CI, making it easy to spot renamed or removed items.

unsafe Code

When unsafe is used, a SAFETY comment MUST be added, in the style supported by Clippy.

TODO: enforce it in CI

Naming Conventions

Names SHOULD adhere to the official API guidelines.

TODO: how to name error types/error enum variants (CannotDoSth vs DoingSth)?

Dependencies

If the same dependency is used in multiples crates within the workspace, that dependency SHOULD be specified in the workspace's Cargo.toml file and workspace crates should import them from there.