comprehensive-rust/STYLE.md

Comprehensive Rust 🦀 Style Guide

The course has been expanded and improved by tons of volunteers like you! Thank you for that! To help ensure a consistent style throughout the course, we have written down some guidelines for you to follow.

Course Philosophy and Design

To contribute effectively, it's helpful to understand the core design principles of Comprehensive Rust. This is not a self-study book; it is a set of slides and notes for an instructor-led course.

Target Audience

The course is designed for an audience of experienced software engineers who are new to Rust. We assume they have 2-3 years of experience in an imperative language like C, C++11+, Java 7+, Python, or Go.

We do not assume familiarity with functional programming concepts or features from more modern languages like Swift or Kotlin. Course material should build upon the concepts that are likely to be familiar to this audience.

Goals

The goal of the course is to provide a solid foundation in Rust within a bounded time frame. This prepares students to continue learning effectively as they begin to apply their new skills on the job.

Pedagogical Principles

We follow a few key principles to make the material effective for learning:

• Build on a Foundation: New Rust concepts should be connected to what a learner already knows, either from their prior language experience or from earlier parts of this course.
• Provide a Working Mental Model (The "No Magic" Rule): As much as possible, avoid telling students to accept syntax or behavior that will be explained later. For everything that appears on the slides or in exercises, we must provide a working mental model that allows the student to understand and use the concept.
• Use a Spiral Approach: To avoid overwhelming the learner, it is highly encouraged to introduce a concept by first providing basic facts and a simplified mental model. The topic can then be revisited later to provide more detail. For example, very early in the course we explain the basics of println!, mention that it is a macro so the usage syntax is a bit unusual, but we don't go into details of format strings or macros. We explain details of format strings later, once we have covered traits and can mention the Debug and Display traits.

Pacing and Structure

The course is designed for approximately 5 hours of teaching per day, typically split into a 3-hour morning session and a 2-hour afternoon session.

This pacing is important context for contributors. Material should be structured to fit this rhythm, with clear sections that can be taught in roughly 45-50 minute blocks to accommodate short breaks and Q&A.

Each slide must include a minutes field in its frontmatter, which specifies the estimated teaching time for that slide. This helps ensure the overall pacing of the course remains consistent.

Course Structure

The course starts with a core Rust Fundamentals curriculum, followed by a collection of specialized deep dives. All students take the Fundamentals course and can then opt into any deep dives that are relevant to them.

The Rust Fundamentals Course

The Rust Fundamentals course provides a solid foundation in a strictly bounded, four-day time frame. This duration is firm, and its scope is carefully managed to focus on the most essential concepts for new Rust programmers.

The overall progression of the course starts with the parts of the Rust language that should be conceptually familiar to most students from other languages. Then we move on to more difficult parts (for example, enums with payloads and generics), and parts that are unique to Rust (lifetimes and the borrow checker).

Contributors should keep this structure in mind. The four-day schedule for the Fundamentals course is completely full, leaving no time slack for new topics. Proposals to add material to the Rust Fundamentals course must also include a plan to shorten or remove existing content. Refinements to existing topics are always welcome. Topics that are not essential for all new Rust programmers should be proposed as new deep dives.

Course Slides

Please take the following into account when updating the course material.

Vertical Space

What looks like pages in a browser, are actually slides in a presentation. It is important to keep this in mind when adding content: we only have limited vertical space. Scrolling up and down should be avoided since it is very jarring for people who attend the class.

You can test the amount of space available using a simple tool. This tool can be used by clicking a toggle button next to the search button on left side of the navbar.

The rectangle has an aspect ratio similar to what you can see when you share your screen on a 16:9 display or projector.

Use the rectangle as a rough guide for how much you can fit on a single slide. If you find yourself adding too much detail, move the details to the speaker notes (see below).

One Core Idea Per Slide

Ideally, each slide should focus on a single, clear takeaway. If a slide introduces a core concept and then explores an important but distinct tangent (e.g., a limitation or an advanced use case), that tangent should be moved to its own slide. This keeps the presentation focused and easier to follow.

Consider the instructor's workflow. If the speaker notes require a long or complex series of live edits, it can be difficult for the instructor to execute well every time. It may be better to add a new slide that presents the desired state of the code.

Pedagogical Flow

When introducing a new concept, start with a simple, relatable, and concrete example. A good opening example grounds the concept for the learner and provides motivation for the more detailed explanation that will follow.

Rust Code

When showing Rust code inline, please use the same spacing as rustfmt: 3 * x instead of 3*x. However, feel free to remove newlines when it can make the code more compact and easier to understand, e.g., you can define a struct on one line if it is not the focus of your example:

struct Person { name: String }

Enclose the code block in <!-- dprint-ignore-start --> and <!-- dprint-ignore-end --> to suppress the automatic formatting. Please use this sparingly.

Use Meaningful Examples

Code samples on the slides should be short and do something meaningful. Avoid using generic placeholders like Foo, Bar, and Baz. Using descriptive names from a real-world, even if simplified, domain makes the code easier to understand and relate to.

Interactive Code Snippets

All Rust code blocks in the course are not static text but are live, editable playgrounds. An important teaching method is for the instructor to edit these snippets live to demonstrate concepts, introduce and fix errors, and explore variations based on student questions.

Contributors should design their slides with this interactivity in mind. The initial state of the code should be a good starting point for a live demonstration.

Code Annotations

Use the ignore annotation for code snippets that are not meant to be complete, self-contained programs. Use compile_fail only when the goal is to demonstrate a specific compiler error that is itself the lesson.

Language and Tone

The courses are written in American English, so write "initialize", not "initialise".

Use an informal, friendly, and concise tone. Remember that the courses are meant to be taught by an experienced programmer to other experienced programmers. When possible, prefer terminology used in the official Rust Book. If a less common but necessary term is used, provide a brief definition.

Exercises

At the end of some sections, learners will actively engage with the material by completing a small exercise. The goal of an exercise is to provide hands-on practice with the concepts just taught.

Please keep the following principles in mind when creating or updating exercises:

• Focused Scope: An exercise should focus on the topic of the preceding section. It should not require knowledge of concepts that have not yet been taught.
• Short Duration: An exercise should be solvable by the target audience in approximately 10-15 minutes. The goal is a quick, successful application of knowledge, not a complex project.
• Clear Instructions: The problem description should be clear and unambiguous.

Speaker Notes

We have extended mdbook with support for speaker notes: content added between <details> ... </details> tags is rendered in a special box that can be collapsed or removed entirely from the slide.

• Speaker notes suggest a narrative structure for the instructor.

• The speaker notes should expand on the topic of the slide. Use them to provide interesting background information for both the instructor and for students who look at the material outside of a class. Remember that many more people will read the course by themselves, so make the notes complete and useful even when there is no Rust expert around.

• For slides with evolving code examples, the notes provide a clear, step-by-step flow for how the code is modified and presented. This is a suggested flow for the instructor's live-coding session within the slide's interactive playground. This includes:

  • The order in which to introduce concepts, how to motivate them.

  • Framing of the code example: the problem it tries to solve, if not obvious.

  • How to demonstrate variations of the code example (e.g., code that does not compile or illustrates a bug).

  • How to change the code on the slide to illustrate the concepts being taught.

  • Where to pause and engage the class with questions.

• Speaker notes should serve as a quick reference for instructors, not a verbatim script. Because instructors have limited time to glance at notes, the content should be concise and easy to scan.

  Avoid long, narrative paragraphs meant to be read aloud:

  Bad: "In this example, we define a trait named StrExt. This trait has a single method, is_palindrome, which takes a &self receiver and returns a boolean value indicating if the string is the same forwards and backwards..."

  Instead, prefer bullet points with background information or actionable teaching prompts:

  Good:

  • Note: The Ext suffix is a common convention.
  • Ask: What happens if the use statement is removed?
  • Demo: Comment out the use statement to show the compiler error.

• Nevertheless, include all of the necessary teaching prompts for the instructor in the speaker notes. Unlike the main content, the speaker notes don't have to fit on a single slide.

More to Explore

Use the "More to Explore" section for valuable topics that are outside the main scope of the class. The content should be placed within the <details> block as shown below:

<details>

...

## More to Explore

...

</details>

This section can contain a deeper explanation of a concept or provide specific pointers to external resources. A link should be accompanied by a brief explanation of what the resource contains and why it is relevant. A vague reference is not helpful, but a specific one can be a great tool for self-learners.

Translations

This section is about what you write in the translation. We describe how to create or update translations elsewhere.

When translating the course, please take the following into account:

• Do not translate:

  • The course name ("Comprehensive Rust 🦀"). If the name is not easily understood in your language, please add the translated version after the original name.
  • Variable names (you should translate the comments, though.)

• If the Rust Book has been translated into your language, please use the same vocabulary.

• The text you write is in Markdown format. Make sure to preserve the original formatting in the translation by marking text as `code`, _emphasis_ and **strong emphasis** like in the original.

• If you find mistakes or things that sound awkward in the original English text, please submit PRs to fix them in the English text! Fixing typos in the translation is great, but we want everybody to benefit from the fixes and that is why we need the fix to be made in the English text too.