You've already forked comprehensive-rust
mirror of
https://github.com/google/comprehensive-rust.git
synced 2025-11-28 16:50:23 +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:
104
STYLE.md
104
STYLE.md
@@ -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
|
example. A good opening example grounds the concept for the learner and provides
|
||||||
motivation for the more detailed explanation that will follow.
|
motivation for the more detailed explanation that will follow.
|
||||||
|
|
||||||
### Rust Code
|
### Use Meaningful Examples
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
Code samples on the slides should be short and do something meaningful. Avoid
|
Code samples on the slides should be short and do something meaningful. Avoid
|
||||||
using generic placeholders like `Foo`, `Bar`, and `Baz`. Using descriptive names
|
using generic placeholders like `Foo`, `Bar`, and `Baz`. Using descriptive names
|
||||||
from a real-world, even if simplified, domain makes the code easier to
|
from a real-world, even if simplified, domain makes the code easier to
|
||||||
understand and relate 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
|
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
|
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
|
initial state of the code should be a good starting point for a live
|
||||||
demonstration.
|
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
|
### `mdbook` and `mdbook-course` Conventions
|
||||||
|
|
||||||
The project uses `mdbook` features in specific ways, as well as a custom
|
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
|
reference is not helpful, but a specific one can be a great tool for
|
||||||
self-learners.
|
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
|
## Translations
|
||||||
|
|
||||||
This section is about what you write in the translation. We describe
|
This section is about what you write in the translation. We describe
|
||||||
|
|||||||
Reference in New Issue
Block a user