Guide to writing idiomatic code at PingCAP and in the TiKV project.
Be mindful that macro definitions are often much easier to write than to read. Prefer to use other abstraction mechanisms (functions, traits) where possible. Don’t use a macro unless there is substantial benefit (usually in significantly reducing boilerplate).
Prefer to use declarative (macro_rules) macros rather than procedural macros.
Prefer to use existing libraries (e.g., Serde) rather than writing new macros.
If writing procedural macros, use the Syn and Quote libraries for parsing and quasi-quoting, respectively.
Do not use the ‘proc macro hack’ to use procedural macros in item position.
Custom derive macros should not do complex code generation (use procedural macros it attribute position instead).
Mostly custom derives should only be used to automatically derive traits.
Custom derives can also be used to generate very simple functions and methods.
E.g., new constructors (derive-new; derive-more) or getters and setters (Getset, though in general you should prefer public fields over generated getters and setters).
Rustfmt will sometimes not format macro uses or definitions. In such cases try to follow Rustfmt conventions as closely as possible. See the Rust style guide for a specification.
<< Functions, methods, and traits | Expressions and statements >>