# Rust's guiding principles

## What is this?

This document proposes a set of "guiding principles" for Rust.

## Rust's charter

Rust is an open-source community creating an easy-to-use language for building safe, reliable programs with consistently great performance. We empower everyone to build systems where resource usage, security and correctness, and long-term maintenance are top considerations. And we do it with pizzazz. :sparkles:

Rust is an open-source community creating an easy-to-use language for building safe, reliable programs with consistently great performance. Rust feels like a high-level language, but offers the performance and safety guarantees

### Rust design principles

The charter declares what we are trying to achieve. This section lists the design principles that tell you how we do it. These principles govern the design of the Rust language, its libraries, and the tooling built around it. These principles are ordered: in the case of unresolvable conflict, we favor things earlier in the list.

* **Safety first.** Safe Rust code is memory safe, data-race free, and free of other kinds of [undefined behavior](https://en.wikipedia.org/wiki/Undefined_behavior). Unsafe Rust code is meant to be well-encapsulated and exposed via a safe interface.
* **You *can* have nice things.** The high-level features in Rust are scalable, performant, and full-featured. We don't expect our users to "drop down" to low-level code, except in extreme cases.
* **Transparent and predictable.** Rust avoids hidden control flow, silent memory allocation, or complex built-in operations. You don't need a lot of context to figure out what some Rust code will do when it runs or what machine code it will generate.
* **Orthogonal, composable, and extensible.** Rust encourages components that can be reused in many ways and in many environments. Rust programs work across mainstream architectures and operating systems by default. We encourage exploration, but we also recognize that exploration sometimes requires standardization.
* **Expose all system capabilities.** Whatever it is you want to do, you should be able to do it in Rust, though it may require jumping through some hoops.
* **Hard to misuse.** We take every opportunity to help users detect bugs and errors in their programs

#### Examples

[Check out this google spreadsheet](https://docs.google.com/spreadsheets/d/1AIixigmD1X_cwuuZ6kfhJs7guACxKIOwd0hALbAtmn0/edit?usp=drive_web&ouid=102772749476739957235)

### Draft

---

* **Enable exploration.**[^py] Nobody has a monopoly on good ideas. We encourage people to try new approaches and alternatives. We believe in a rich ecosystem of cooperative, interoperable crates; however, we also recognize that sometimes the best way to enable exploration is to standardize (judiciously).

## FAQ

### "Easy to use" and "hard to misuse" can be in tension, shouldn't they be separated?

Arguably, yes, but we decided to combine them because they can also benefit one another, if the design is right. A design which is hard to misuse is also one that guides you down the correct path. The challenge then is to satisfy both at once (i.e., to avoid "hard to use altogether" and to avoid "easy to use and misuse"). Separating these two principles didn't seem to give guidance on how to handle any particular situation that we could come up with.

Insight:

* portability is WWOT?
* But maybe WWOT is too vague and general: what ISN'T WWOT apart from "easy to learn"?
* efficiency, safety, these are all elements of WWOT, right?
* I think the charter is something that "wears well over time"
*

Example of WWOT that is not MM:

* trailing semicolons
* .await syntax
*

### Rust community principles (draft)

These principles describe the ways that individual members of Rust's community act.

* ✨ *Focus on the user.* We help our users be productive and empowered, first and foremost. We aim to make Rust useful and helpful, and we aim to make all of our users feel comfortable and welcome.
* 😍 *Find joy.* We are always looking for ways to make working on Rust fun and enjoyable.[^emoji]
* 🤝 *Earn trust.* You earn trust by bringing good ideas to the table and recognizing when other people do.
* 🎁 *Give trust.* XXX empower people
* 👋 *Show up.* Bring your expertise and be willing to argue for what you think is right.
* ✅ *Follow through.* say what you will do, and do what you say, and speak up if you know you can’t (it’s ok).
* ☯️ *[OODA].* Finding the perfect design requires iteration. Think big but start small; don't be afraid to change course when it's the right thing to do.
* 💰 *Pay it forward.* Project members recognize exceptional potential, intentionally develop new members, and take their coaching role seriously.
* XXX expertise, recognize good ideas XXX deliver better results when you recognize/leverage expertise of others

[^emoji]: Like emojis! :grin:

[OODA]: https://en.wikipedia.org/wiki/OODA_loop

---

# Older content

* *Learn from others, but not afraid to do our own thing.* Rust aims to be familiar, but sometimes there is a better way.
* Joy!
* *People first.*
* *Avoid high-stress deadlines; train model.*
* *Stability without stagnation.*
* Iterate, iterate, iterate.
* True artists deliver results.
* Take the time to get it right.
* Pipeline from exploration to collaboration/cooperation/stability.
* *We work in the open from design to implementation.* [^nnr]
* *Teams drive decision making.*
* Path to core.
* Easy to get started.
* Positive sum
* "Stability without stagnation"
* "Take the time to get it right"
- Enabling experimentation
- but "True artists ship"
* "True artists ship"
* something something "nothing is so important that it can't catch the next train"
* Accessible.
* Respect beginners. Beware the curse of knowledge.
* Everybody is a beginner in something.
* Stability without stagnation.
* Learn from others, but not afraid to do our own thing.
* No new rationale.
* Respect that people have differences of opinion and that every design or implementation choice carries a trade-off and numerous costs. There is seldom a right answer.
* Please keep unstructured critique to a minimum. If you have solid ideas you want to experiment with, make a fork and see how it works.

[^nnr]: aka, "no new rationale'"

### Design patterns and examples that embody these principles

This section describes examples of design patterns and decisions and strategies

* *Say what you mean.* Make distinctions via explicit methods (`wrapping_add`) instead of overloading a single operator.
* Bounds checks
* Overflow checking
* `.await` trades away similarity with other languages for self-consistency and orthogonality within Rust
* **The `Rc` and `Arc` types** provide control over whether to use
* 'Opt-in `Copy`' -- chose to make Copy something you had to explicitly implement because semver
* Orthogonality --
* **Auto traits** and **auto trait leakage** -- was a tradeoff:
* Editions: a good balance embodying "stability without stagnation"
* train model for managing releases
* compiler error messages
* For **error handling**, we chose to propagate errors via `Result` types rather than exceptions because use the `?` operator to have "manually propagated" errors. The "familiar" thing from other languages is exceptions that propagate silently. The goal was to make propagation "quiet" so as to highlight the

### Examples

* **Bounds checks and iterators**: We insert bounds checks on accesses to arrays because "correctness and safety are iron-clad", and that matters more than "performant by default". We don't do fancier things like requiring you to statically prove your accesses are in-bounds because we value "accessibility above all", and that would be complex. There are unsafe methods that can be used to skip bounds checks ("completeness"). Further, the idiomatic way to iterate in Rust is with iterators, which encapsulate those unsafe methods, and thus most Rust programs do not pay for bounds checks when iterating ("performant by default").
* These principles present a strong case for going further.
* For our **await syntax**, we chose `expr.await` instead of `await expr` because it "wears well over time", even though it is (mildly, perhaps) less "familiar and easy to learn".
* **The `Rc` and `Arc` types** provide control over whether to use
* 'Opt-in `Copy`' -- chose to make Copy something you had to explicitly implement because semver
* **Auto traits** and **auto trait leakage** -- was a tradeoff:
* Chose this because "Parallelizable by default" beats ""
* convenient vs semver?
* Principles in tension: (convenience and not being forced to think about things you don't otherwise) vs (semver and ...)
* we wanted people to be parallel-safe by default
* "what are people forced to think about"
*

### Counterexamples

* The **"omit the trailing `;` to produce a result" rule** produces a lot of confusion and may be a case where we undervalued "familiar and easy to learn" (users are not accustomed to `;` being significant). However, the general rule of "everything is an expression" feels like a good example of "wears well over time".
* The **module system** is a case where we undervalued "familiar and easy to learn"; see [boats's blog post](https://without.boats/blog/the-rust-module-system-is-too-confusing/) for an exposition. We attempted to correct for this in Rust 2018.

### Semver hazards

* Inference based on impls that exist-- semver hazards
*

### Interesting examples

* auto-clone
*

### Changes that these suggest