3 This document collects the emerging principles, conventions, abstractions, and
4 best practices for writing Rust code.
6 Since Rust is evolving at a rapid pace, these guidelines are
7 preliminary. The hope is that writing them down explicitly will help
8 drive discussion, consensus and adoption.
10 Whenever feasible, guidelines provide specific examples from Rust's standard
13 ### Guideline statuses
15 Every guideline has a status:
17 * **[FIXME]**: Marks places where there is more work to be done. In
18 some cases, that just means going through the RFC process.
20 * **[FIXME #NNNNN]**: Like **[FIXME]**, but links to the issue tracker.
22 * **[RFC #NNNN]**: Marks accepted guidelines, linking to the rust-lang
23 RFC establishing them.
25 ### Guideline stabilization
27 One purpose of these guidelines is to reach decisions on a number of
28 cross-cutting API and stylistic choices. Discussion and development of
29 the guidelines will happen primarily on https://internals.rust-lang.org/,
30 using the Guidelines category. Discussion can also occur on the
31 [guidelines issue tracker](https://github.com/rust-lang/rust-guidelines).
33 Guidelines that are under development or discussion will be marked with the
34 status **[FIXME]**, with a link to the issue tracker when appropriate.
36 Once a concrete guideline is ready to be proposed, it should be filed
37 as an [FIXME: needs RFC](https://github.com/rust-lang/rfcs). If the RFC is
38 accepted, the official guidelines will be updated to match, and will
39 include the tag **[RFC #NNNN]** linking to the RFC document.
41 ### What's in this document
43 This document is broken into four parts:
45 * **[Style](style/README.md)** provides a set of rules governing naming conventions,
46 whitespace, and other stylistic issues.
48 * **[Guidelines by Rust feature](features/README.md)** places the focus on each of
49 Rust's features, starting from expressions and working the way out toward
50 crates, dispensing guidelines relevant to each.
52 * **Topical guidelines and patterns**. The rest of the document proceeds by
53 cross-cutting topic, starting with
54 [Ownership and resources](ownership/README.md).
56 * **APIs for a changing Rust**
57 discusses the forward-compatibility hazards, especially those that interact
58 with the pre-1.0 library stabilization process.
60 > **[FIXME]** Add cross-references throughout this document to the tutorial,
61 > reference manual, and other guides.
63 > **[FIXME]** What are some _non_-goals, _non_-principles, or _anti_-patterns that