This document collects the emerging principles, conventions, abstractions, and best practices for writing Rust code.

Since Rust is evolving at a rapid pace, these guidelines are very preliminary. The hope is that writing them down explicitly will help drive discussion, consensus and adoption.

Whenever feasible, guidelines provide specific examples from Rust's standard libraries.

Until the guidelines are moved into rust-lang (see below), you can find a rendered snapshot at http://aturon.github.io/.

Like http://rustbyexample.com/, this guidelines document is written as a gitbook. You can install gitbook by running

npm install gitbook -g 

After installing, just run

gitbook serve 

in the root of the repository to continuously serve your local copy of the guidelines.

Every guideline has a status:

• [FIXME]: Marks places where there is clear work to be done that does not require further discussion or consensus.

• [OPEN]: Marks open questions that require concrete proposals for further discussion.

• [RFC]: Marks concrete, proposed guidelines that need further discussion to reach consensus.

• Untagged guidelines are considered well-accepted. Ed. note: to begin with, there are almost none of these!

To begin with, this document will exist under https://github.com/aturon/rust-guidelines and will have no official status. This brief early stage is mainly intended as a sanity check, and to try to get the draft in as good of shape as possible before bringing it to the full community.

Pull requests very welcome!

After completing a first draft of the guidelines, we will:

1. Move the repository into the rust-lang organization, and
2. Begin a formal process to migrate guidelines to fully accepted status.

The precise mechanics for guideline adoption are to be determined, but will likely resemble the Rust RFC process.

This document is broken into four parts:

• Style provides a set of rules governing naming conventions, whitespace, and other stylistic issues.

• Guidelines by Rust feature places the focus on each of Rust's features, starting from expressions and working the way out toward crates, dispensing guidelines relevant to each.

• Topical guidelines and patterns. The rest of the document proceeds by cross-cutting topic, starting with Ownership and resources.

• APIs for a changing Rust discusses the forward-compatibility hazards, especially those that interact with the pre-1.0 library stabilization process.

[FIXME] Add cross-references throughout this document to the tutorial, reference manual, and other guides.

[OPEN] What are some non-goals, non-principles, or anti-patterns that we should document?