Skip to main content

Rust Style Guide

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

Uniform Formatting and Linting

To ensure high quality code, we have imposed strict linting, testing, and formatting requirements.

For this goal, the following files and directories must be uniform across all Rust repositories:

  • .editorconfig: Specifies file formatting rules that must be followed
  • .github/workflows/rust_ci.yml: Specifies GitHub Workflow actions that must pass prior to merge
  • .github/workflows/editorconfig_check.yml: Ensures no file formatting violations prior to merge
  • .cargo/config.toml: Specifies extra compiler checks for stricter linting
  • .cargo-husky/hooks/: Scripts that must succeed before git commit is allowed to execute
  • .gitignore: One of two .gitignore files, one shared by Rust libraries and one shared by Rust services
  • Code coverage configuration (coming soon)

❗ Don't worry! We create and update these automatically through Terraform.

These files should only be edited in the tf-github repository. Changes will be applied to all Rust repositories in the Arrow organization.


  • Add a newline to tf-github/templates/rust-all/.editorconfig.
  • Make a pull request, get approvals, merge to main
  • A new commit is pushed to the default branch of each Rust repository controlled by Terraform.
    • Each repository now has an updated .editorconfig file.

💂‍♂️ 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
  • taplo format --check: Format TOML files to Arrow's style guide
  • cspell --words-only --unique "**/**" -c .cspell.config.yaml: Spell check all files in the repository
  • Check for all broken links in the repository
  • Check for all editorconfig violations in the repository

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!


/// 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.


//! 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.