PingCAP Style Guide

Guide to writing idiomatic code at PingCAP and in the TiKV project.

---

Project maintained by pingcap Hosted on GitHub Pages — Theme by mattgraham

Formatting

Use Rustfmt: cargo fmt --all; do not customise rustfmt settings (rustfmt.toml), except for temporary work-arounds. You can install Rustfmt using rustup component add rustfmt.

Rustfmt is not complete, there is some code where Rustfmt will not reformat code. A common example is some bodies of macro_rules! items and some macro uses. In these cases, follow the Rust formatting style guide.

When writing macro uses which Rustfmt does not format, if the content is code-like, try to follow the formatting style guide. If the content is tabular, arrange the data in columns using spaces, not tabs, on multiple-of-four column positions.

Always use Unix line endings (\n).

Rationale

• Make code consistent with the Rust ecosystem to lower barriers to entry.
• Make code self-consistent to make code reading easier.

Imports

Rustfmt will format imports but permits several different styles.

• Avoid extern crate, except for macros which are used in many files (e.g., logging macros). Group extern crates together.
• Group all imports together.
• Group re-exports together (pub use ...;).
• Use a single nested import, rather than multiple imports, for each crate.
  • This can be achieved mechanically by using the merge_imports option with Rustfmt.
• Prefer to use absolute paths rather than relative paths (i.e., crate::.. rather than super::... or self::...). Exception: when re-exporting from sub-modules, use relative paths (e.g., pub use self::foo::bar;).

Example:

use crate::{
    pd::client::{Cluster, RetryClient},
    util::GLOBAL_TIMER_HANDLE,
    Result,
};
use futures::{
    compat::Compat01As03,
    prelude::*,
    ready,
    task::{Context, Poll},
};
use std::{
    pin::Pin,
    sync::Arc,
    time::{Duration, Instant},
};

pub use self::Request;

// ...

#[cfg(test)]
mod test {
    use super::*;
    use tokio_timer::timer::Handle;

    // ...
}

Rationale

• Ecosystem conventions.
• Modern conventions.
• Self-consistency.
• Make it easier to figure out where names come from without IDE support
• Make it easier to see which crates and modules a module depends on.
• Make it easier to move or copy imports between modules.
• Less duplication of paths.
• More logical grouping of items - import structure reflects the module structure.

<< Introduction | Naming >>