1
0
mirror of https://github.com/google/comprehensive-rust.git synced 2025-10-09 10:55:26 +02:00

docs(style): Reorganize code block and formatting sections (#2928)

- Consolidates all guidance related to code block mechanics under a new
top-level heading, "Code Blocks Mechanics".
- Moves the "Rust Code Formatting" guidance to be a subsection under
this new heading.
- The rest of the former "Rust Code" section is now directly under
"Course Slides".

This restructuring improves the logical flow of the style guide by
grouping all code-related formatting and tooling conventions into a
single, easy-to-find section.
This commit is contained in:
Dmitri Gribenko
2025-09-24 10:25:01 +02:00
committed by GitHub
parent a6e18b6866
commit 4671b3455b

104
STYLE.md
View File

@@ -129,33 +129,14 @@ 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:
<!-- dprint-ignore-start -->
```rust
struct Person { name: String }
```
<!-- dprint-ignore-end -->
Enclose the code block in `<!-- dprint-ignore-start -->` and
`<!-- dprint-ignore-end -->` to suppress the automatic formatting. Please use
this sparingly.
#### Use Meaningful Examples
### 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
### Plan 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
@@ -166,37 +147,6 @@ 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 Blocks
Code blocks are a critical part of the course. To ensure they are consistent and
behave as expected, please follow these conventions.
#### Language Identifiers
Use the following language identifiers for fenced code blocks:
- **`rust`**: For Rust code examples.
- **`shell`**: For shell commands. Use a `$` prompt for consistency. Omit the
prompt for multi-line commands or when the output is shown.
- **`bob`**: For ASCII art diagrams generated by `mdbook-bob`.
- **`ignore`**: For code snippets that are not complete, self-contained programs
or are for illustrative purposes only and should not be compiled.
#### mdbook Annotations
You can add annotations to Rust code blocks to control how they are tested and
displayed:
- **`editable`**: Makes the code block an interactive playground where users can
edit and run the code. This should be used for most Rust examples.
- **`compile_fail`**: Indicates that the code is expected to fail compilation.
This is used to demonstrate specific compiler errors.
- **`should_panic`**: Indicates that the code is expected to panic when run.
- **`warnunused`**: Re-enables `unused` lints for a code block. By default, the
course's test runner disables lints for unused variables, imports, etc., to
avoid distracting warnings. Use this annotation only when a warning is part of
the lesson.
### `mdbook` and `mdbook-course` Conventions
The project uses `mdbook` features in specific ways, as well as a custom
@@ -318,6 +268,56 @@ 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.
## Code Blocks Mechanics
Code blocks are a critical part of the course. To ensure they are consistent and
behave as expected, please follow these conventions.
### Language Identifiers
Use the following language identifiers for fenced code blocks:
- **`rust`**: For Rust code examples.
- **`shell`**: For shell commands. Use a `$` prompt for consistency. Omit the
prompt for multi-line commands or when the output is shown.
- **`bob`**: For ASCII art diagrams generated by `mdbook-bob`.
- **`ignore`**: For code snippets that are not complete, self-contained programs
or are for illustrative purposes only and should not be compiled.
### mdbook Annotations
You can add annotations to Rust code blocks to control how they are tested and
displayed:
- **`editable`**: Makes the code block an interactive playground where users can
edit and run the code. This should be used for most Rust examples.
- **`compile_fail`**: Indicates that the code is expected to fail compilation.
This is used to demonstrate specific compiler errors.
- **`should_panic`**: Indicates that the code is expected to panic when run.
- **`warnunused`**: Re-enables `unused` lints for a code block. By default, the
course's test runner disables lints for unused variables, imports, etc., to
avoid distracting warnings. Use this annotation only when a warning is part of
the lesson.
### Rust Code Formatting
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:
<!-- dprint-ignore-start -->
```rust
struct Person { name: String }
```
<!-- dprint-ignore-end -->
Enclose the code block in `<!-- dprint-ignore-start -->` and
`<!-- dprint-ignore-end -->` to suppress the automatic formatting. Please use
this sparingly.
## Translations
This section is about what you write in the translation. We describe