Skip to main content

Rust Style Guide

⚡ View the sidebar (right) for the rapid navigation.

💂‍♂️ Formatting, Linting and Static Analysis​

Rust does not have an official style guide. It relies on the rustfmt tool.

We use husky for pre-commit hooks.

Husky will automatically run the following when you attempt to commit changes:

  • rustfmt: Format code to Rust's style guide
  • cargo check: Check a local package and all of its dependencies for errors
  • cargo test: Run unit and integration tests
  • cargo clippy -- -D warnings: A collection of lints to catch common mistakes and improve your Rust code. Source Code

Any errors (including warnings) must be resolved before committing code.

❗ These same checks will be run in CI, and must pass before the code can be merged.

❗ cargo fuzz and rudra may also be introduced at a later date.

Additional Linters​

rustc has a series of lints, or checks that run during compilation.

We configure our builds for stricter linting, including missing docs and unsafe code.

❗ These are warnings (instead of errors) to ease development, however:

  • These warnings will be treated as errors in the continuous integration (CI) pipeline.
  • They must be resolved before a Pull Request can be merged.

💬 Docstrings​

cargo doc is used to build documentation.

"Docstrings" are comments that explain the purpose of a function or structure.

When documenting the "next" item, docstrings start with ///. Markdown syntax is supported!

Example:

/// Returns a person with the name given them
///
/// # Arguments
///
/// * `name` - A string slice that holds the name of the person
///
/// # Examples
///
/// ```
/// // You can have rust code between fences inside the comments
/// // If you pass --test to `rustdoc`, it will even test it for you!
/// use doc::Person;
/// let person = Person::new("name");
/// ```
pub fn new(name: &str) -> Person {
    Person {
        name: name.to_string(),
    }
}

When documenting an enclosing item, //! is used.

  • This includes the "crate comment" at the top of the source file.

Example:

//! The Foo module does X
//! This is the "crate documentation"

mod foo {
    //! This is documentation for the `foo` module.
    //!
    //! # Examples

    // ...
}

Read more about Rust docs here.

📃 License Notice​

Every file should start with a license notice.

The license may vary from repository to repository.

Check with the #legal team if unclear which license to use.