frewsxcv / rust-guidelines Goto Github PK

% Rust Guidelines [working title]

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 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.

For now, you can find a rendered snapshot at http://aturon.github.io/. After some infrastructure work, the snapshot will move somewhere more official.

Building the document

Like http://rustbyexample.com/, this guidelines document is written in the gitbook style. It can be compiled with a prototype tool, rustbook that provides a minimal subset of gitbook's functionality on top of rustdoc.

Guideline statuses

Every guideline has a status:

• [FIXME]: Marks places where there is more work to be done. In some cases, that just means going through the RFC process.

• [FIXME #NNNNN]: Like [FIXME], but links to the issue tracker.

• [RFC #NNNN]: Marks accepted guidelines, linking to the rust-lang RFC establishing them.

Guideline stabilization

One purpose of these guidelines is to reach decisions on a number of cross-cutting API and stylistic choices. Discussion and development of the guidelines will happen primarily on http://discuss.rust-lang.org/, using the Guidelines category. Discussion can also occur on the guidelines issue tracker.

Guidelines that are under development or discussion will be marked with the status [FIXME], with a link to the issue tracker when appropriate.

Once a concrete guideline is ready to be proposed, it should be filed as an FIXME: needs RFC. If the RFC is accepted, the official guidelines will be updated to match, and will include the tag [RFC #NNNN] linking to the RFC document.

What's in this document

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.

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