wip

book.toml

@@ -4,3 +4,8 @@ language = "en"
 multilingual = false
 src = "src"
 title = "Rustacean Principles"
+
+
+[output.html.fold]
+enable = true
+level = 0

src/SUMMARY.md

@@ -3,11 +3,20 @@
 - [What is Rust?](./what_is_rust.md)
 - [Rust empowers by being...](./how_rust_empowers.md)
     - [⚙️ Reliable](./how_rust_empowers/reliable.md)
+        - [Type safety](./how_rust_empowers/reliable/type_safety.md)
+        - [Consider all cases](./how_rust_empowers/reliable/consider_all_cases.md)
     - [🐎 Performant](./how_rust_empowers/performant.md)
+        - [Zero-cost abstractions](./how_rust_empowers/performant/zca.md)
+        - [Specify only what's necessary](./how_rust_empowers/performant/zca.md)
     - [🥰 Supportive](./how_rust_empowers/supportive.md)
+        - [Polished developer experience](./how_rust_empowers/supportive/polished.md)
     - [🧩 Productive](./how_rust_empowers/productive.md)
+        - [Ecosystem](./how_rust_empowers/productive/ecosystem.md)
+        - [Upgrades are easy and painless](./how_rust_empowers/productive/ecosystem.md)
     - [🔧 Transparent](./how_rust_empowers/transparent.md)
+        - [No global costs](./how_rust_empowers/transparent/no_global_costs.md)
     - [🤸 Versatile](./how_rust_empowers/versatile.md)
+        - [Expose all system capabilities](./how_rust_empowers/productive/expose_capabilities.md)
 - [How to Rustacean](./how_to_rustacean.md)
     - [💖 Be kind and considerate](./how_to_rustacean/be_kind.md)
     - [✨ Bring joy to the user](./how_to_rustacean/bring_joy.md)

src/how_rust_empowers/performant.md

@@ -25,6 +25,6 @@ What are some of the ways that we make Rust feel **performant**?
 
 Rust borrowed the idea of zero-cost abstractions from the C++ community. Bjarne Stroustroup defined zero-cost abstractions as, "What you don't use, you don't pay for. And further: What you do use, you couldn't hand code any better." We design our abstractions with these goals in mind as well.
 
-### Avoid overspecifying machine details
+### Specify only what's necessary
 
 Many details of Rust are left deliberately unspecified. For example, unless users manually add a `repr` attribute, Rust structs and enums can be laid out in memory however the compiler sees fit. This allows us make optimizations like reordering struct fields to eliminate padding and reduce size, or representing `Option<&T>` as a single, nullable pointer. (Of course, reserving this freedom works against [transparency] and [versatility], which is why we have the option to specify the `repr`.)

src/how_rust_empowers/reliable.md

@@ -17,37 +17,5 @@ Reliability can also be at odds with [versatility]. Our ability to make somethin
 
 What are some of the ways that we make Rust feel **reliable**?
 
-### Type safety (but with an unsafe escape hatch)
-
-*Makes Rust code feel **reliable** but can work against Rust feeling [productive] and [supportive].*
-
-Type safety is a key element to reliability. We ensure that safe Rust code is free of "undefined behavior", which is the term that compiler authors use to refer to things like segfaults, data races, and out-of-bounds memory accesses.
-
-Type safety is not a suggestion: we don't accept **almost safe** APIs, which are safe so long as you don't do "unreasonable" things. For example, we would not accept a safe API that avoids undefined behavior so long as no cycles exist between ref-counted objects. Reasonable people do "unreasonable" things in code all the time, either because they don't yet know what is reasonable or not, or because the complexity of the system gets away from them. The role of the compiler is to manage that for you.
-
-However, type safety carries a cost, too. It adds complexity, which can work against Rust feeling [productive]. It also makes Rust more complex and hard to learn, which can work against feeling [supportive] -- we work hard on our error messages and documentation precisely to help mitigate this cost. Precisely because of these costs, we have imposed some limits on what Rust's type system tries to achieve:
-
-* We employ **runtime checks** for certain kinds of error conditions. For example, we do not try to prove that indexes are within bounds, but instead check an expression like `vec[i]` to ensure that `i < vec.len()`. Proving conditions about the specific value of a variable (in this case, `i` or the length of a vector) would be a "big step up" in complexity of the type system. Rust's choice not to do so decreases that feeling of reliability, but with massive benefits to [productivity].
-* We permit **unsafe code**, which gives authors an escape hatch from the type system. This means that we can support many kinds of systems programming patterns while keeping the type system itself relatively simple. (For example, the system of ownership and borrowing cannot express doubly linked lists, but they can be implemented with unsafe code.)
-    * However, we do expect authors to **encapsulate** their unsafe code, presenting a safe interface to the world at large. This works against the feeling of [productivity] for unsafe code authors (it's more complex to think about how to encapsulate things) but with great benefits for reliability for the rest of the world.
-
-### Consider all cases
-
-Rust generally aims to make sure that you 'acknowledge' or consider all cases. You can see this in `match` statements, which require exhaustive matching (many other languages permit you to leave off match arms that you believe cannot occur); when matching, we also require that users list all fields in a struct, or acknowledge (with `..`) that they have not done so. Forcing users to consider all cases helps make Rust feel reliable, but it can come at the cost of feeling [productive]. This is why we frequently pay careful attention to the details of 
-
-A good case study for the tradeoffs involved is error handling. The traditional approach to error handling for a long time was exceptions. Exceptions are great for feeling [productive], as they allow errors to quietly pass through any amount of code. However, the result is a proliferation of hidden control-flow paths that are very hard to reason about. In practice, recovering from exceptions is fraught with error, and hence they work against the feeling of reliability. The problem is that typical mechanisms such as returning an error code are also not reliable; it's too easy to forget to check for an error.
-
-Rust instead adopts the approach pioneered in functional languages of returning an enum. The `Result` enum allows one to signal an error in a way that *forces* the error to be considered. Still, the most common way to handle an error is to propagate it to your caller, and in order to feel productive, it's important that this operation be *concise*. Rust's `?` operator was added to restore productivity while ensuring that error paths are still visible to users and are not completely overlooked.
-
-### Cargo's dependency system
-
-Cargo's dependency system is geared towards reproducible builds. Once an application builds, the `Cargo.lock` file ensures that you don't get surprised by new versions of dependencies that you didn't request.
-
-### Explicit error handling with `?`
-
-Rust eschews exceptions in their traditional form, instead preferring to leverage `Result` types. The `?` operator is at once concise and visible, making it possible to see where errors occur without obscuring the "happy path" where the code is successful. The `?` operator also enables "error type adaptation", which is an example of [polish](./polish.md).
-
-**Too little:** Exceptions that invisibly propagate across stack frames. Experience has shown that programmers have a hard time ensuring that the state of their program is consistent after exceptions are thrown (this is why Rust panics are reserved for irrecoverable error conditions).
-
-**Too much:** Requiring a lot of ceremony on each error could make programs more reliable, but would work against [empowering](./empowering.md) or [polished](./polished.md). 
-
+* [Type safety](./reliable/type_safety.md): Safe Rust code is guaranteed to avoid undefined behavior.
+* [Consider all cases](./reliable/consider_all_cases.md): Rust encourages authors to consider all the possible states that their program might reach.