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

Rust

Contents

• Introduction
• Formatting
• Naming
• Comments
• Modules and crates
• Data structures
• Implementing traits
• Functions, methods, and traits
• Macros
• Expressions and statements
• Error handling
• Unsafe code
• Performance

Introduction

You use Rustfmt and Clippy. You should use Rustfmt with no customisation (rustfmt.toml file). You should use Clippy with the same set of disabled lints as TiKV. The easiest way to do that with TiKV is to use make clippy rather than cargo clippy.

Idiomatic Rust programming changed with the 2018 edition. For example, how imports are written and which lifetimes can be elided. You should always use Rust 2018, and should use the modern idioms (such as avoiding extern crate, importing macros using use). Be aware when reading older code that it may be from pre-2018 edition.

When writing Rust where there are competing conventions, e.g., with FFI and C or interacting with protocol buffers, stick to the Rust conventions rather than the domain conventions. E.g., types which are wrappers around C types should have CamelCase names even if the underlying types have snake_case names (though the bindings themselves will have the C names).

Further reading

The following resources were useful in making this guide, there is often more detail than could be accommodated here.

• Formatting guide
• API design guidelines
• Killercup’s style guide
• Rust design patterns
• The nomicon
• Convention RFCs in the RFC repo.

Open questions

FIXME: address these

• error handling
• callbacks
  • could be futures?
  • performance if we need conversion layer (widely used)
• metrics?
  • global vs local (better perf) vs thread local metrics (maybe the best, but not widely used)
• could we turn on some pedantic lints or use some rustfmt options?
  • Rustfmt
    • merge_imports
    • merge_derives
    • condense_wildcard_suffixes
    • newline_style = “Unix”
    • normalize_comments
    • normalize_doc_attributes
    • reorder_impl_items
    • report_todo
    • unstable_features
    • use_field_init_shorthand
    • use_try_shorthand
  • Clippy