src/doc/style/README.md

   1 % Style Guidelines
   2
   3 This document collects the emerging principles, conventions, abstractions, and
   4 best practices for writing Rust code.
   5
   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.
   9
  10 Whenever feasible, guidelines provide specific examples from Rust's standard
  11 libraries.
  12
  13 ### Guideline statuses
  14
  15 Every guideline has a status:
  16
  17 * **[FIXME]**: Marks places where there is more work to be done. In
  18   some cases, that just means going through the RFC process.
  19
  20 * **[FIXME #NNNNN]**: Like **[FIXME]**, but links to the issue tracker.
  21
  22 * **[RFC #NNNN]**: Marks accepted guidelines, linking to the rust-lang
  23   RFC establishing them.
  24
  25 ### Guideline stabilization
  26
  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).
  32
  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.
  35
  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.
  40
  41 ### What's in this document
  42
  43 This document is broken into four parts:
  44
  45 * **[Style](style/README.md)** provides a set of rules governing naming conventions,
  46   whitespace, and other stylistic issues.
  47
  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.
  51
  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).
  55
  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.
  59
  60 > **[FIXME]** Add cross-references throughout this document to the tutorial,
  61 > reference manual, and other guides.
  62
  63 > **[FIXME]** What are some _non_-goals, _non_-principles, or _anti_-patterns that
  64 > we should document?