Header Comment
file description
↓
Module-Level Attributes
↓
Includes
std
↓
external crates
↓
current crate
↓
Constants
static & const values
↓
Types Declaration
structs, enums, traits
↓
Type Implementations
methods & trait impls
repeat as needed
↓
General Functions
free functions & helpers
↓
Tests
unit & integration tests
The example used throughout is a hypothetical `pill_factory` module - a
self-contained illustration of the layout rules.
---
### 1. Header Comment
The file must open with a `//!` module-level doc comment.
For the required structure and writing rules, see
[Module-Level Comments](#module-level-comments)
---
### 2. Module-Level Attributes
Optional. Contains all the attributions required.
```rust
#![warn(missing_docs)]
#![warn(clippy::pedantic)]
#![deny(unsafe_code)]
```
---
### 3. Includes
Contains all the includes required in the file.
```rust
// Standard library
use std::sync::atomic::{AtomicU64, Ordering};
use std::time::Duration;
// External crates
use anyhow::{ensure, Result};
use serde::{Deserialize, Serialize};
// Current crate
use crate::inventory::IngredientInventory;
use crate::quality::QualityInspector;
```
- Three groups, always in this order:
1. Standard library (`std::…`)
2. External crates (third-party dependencies)
3. Current crate (`crate::…`)
- Each group is separated by a blank line and preceded by a `// Group name` comment.
- Within a group, imports are not further sorted. They follow logical proximity.
---
### 4. Constants
Optional. Contains all `const` and `static` items.
- Opened with a double-bar separator: `// =====…` (80 col).
- `pub` items appear before private ones.
- For doc-comment rules, see [Constants & Statics](#constants--statics).
---
### 5. Types & Implementations
Core of the file.
Groups of multiple type declarations and implementations right below them.
Groups repeat multiple times.
Each type group follows a fixed sub-order:
1. Type declaration - `struct`, `enum`, or `trait`.
2. Inherent `impl` block(s) - methods on the type itself.
3. Trait `impl` block(s) - trait implementations for the type.
#### 5a. Type Declaration
- Separator comment names the type (`// =====…`).
- Derive macros go on the same line as `#[derive(…)]`.
- For doc-comment rules, see [Types](#types-structs-enums-traits).
#### 5b. Inherent Implementation
- Single-dash separator (`// -----…`) divides methods into logical groups
(e.g. *Construction*, *Property getters*, *Production*).
- Groups appear in order of typical call-site usage: construct first, then queries, then mutations.
- For doc-comment and step-label rules, see [Functions & Methods](#functions--methods) and
[Step Labels](#step-labels).
#### 5c. Trait Implementation
- Trait impls come after all inherent impl blocks for the same type.
- For doc-comment rules, see [Functions & Methods](#functions--methods).
---
### 6. General Functions
- Free functions and module-level helpers that do not belong to any single
type live here.
- For doc-comment, step-label, and safety-comment rules, see
[Functions & Methods](#functions--methods),
[Step Labels](#step-labels), and
[Safety Comments](#safety-comments).
---
### 7. Tests
- Always the last section in the file.
- Wrapped in `#[cfg(test)] mod tests { … }` with `use super::*;`.
- Test helpers (non-`#[test]` functions) appear before the test cases.
- Test function names describe the behaviour being verified, not the
implementation detail.
- For doc-comment and step-label rules, see
[Functions & Methods](#functions--methods) and
[Step Labels](#step-labels).
---
### Quick Reference
| # | Section | Separator | Contents |
|---|---------|-----------|----------|
| 1 | Header Comment | *(none)* | `//!` module doc |
| 2 | Attributes | *(none)* | `#![]` crate-level lints |
| 3 | Includes | `// Group` comments | `std` → extern → `crate` |
| 4 | Constants | `// ====…====` | `const` & `static` |
| 5 | Types + Impls | `// ====…====` per type | struct/enum/trait → `impl` → trait `impl` |
| 6 | General Functions | `// ====…====` | free functions & helpers |
| 7 | Tests | `// ====…====` | `#[cfg(test)] mod tests` |
## Comments & Documentation
This section is the single reference for how to write every kind of comment
in a Pill source file. For where each comment kind belongs in the file
layout, see [Source File Layout](#source-file-layout).
### Module-Level Comments
Every file opens with a `//!` block. See the [Header Comment](#_1-header-comment)
section in Source File Layout for the required structure
(`# Responsibilities` / `# Design`).
| Section | Required? | Purpose |
|---------|-----------|---------|
| One/Two-line summary | Yes | Few first lines; states what the file provides. |
| `# Responsibilities` | Yes | Bullet list of what this module owns. |
| `# Design` | Recommended | Architectural notes, cross-type relationships. |
- Use intra-doc links to reference key types: `` [`PillFactory`] ``.
---
### Item-Level Comments
Every public and private item carries a `///` doc comment.
Private items use `///` when their behaviour is non-trivial.
#### Types (structs, enums, traits)
2-4 lines: a 1-line summary followed by 1-3 lines of elaboration.
```rust
/// Physical shape produced by the pill press.
///
/// The shape determines the tooling used during manufacturing and influences
/// the pill's appearance and ease of swallowing.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum PillShape {
/// A conventional circular pill.
Round,
/// An elongated pill with rounded ends.
Capsule,
/// A pill divided by a central score line.
Scored,
}
```
- Summary line explains what the type represents.
- Elaboration explains why it exists or its role in the system.
- Enum variants each get their own `///` line.
#### Functions & Methods
```rust
/// Validates a pill recipe before production begins.
///
/// # Errors
///
/// Returns an error if the name is empty, the active ingredient is missing, or
/// the recipe produces a pill with zero total weight.
fn validate_recipe(recipe: &PillRecipe) -> Result<()> { /* … */ }
```
| Section | When to use |
|---------|-------------|
| *(summary line)* | Always. Describes what the function does. |
| `# Errors` | When returning `Result`. Lists every error condition. |
| `# Safety` | When the function is `unsafe`. Lists every caller obligation. |
| `# Examples` | For key public API surfaces. Minimal working call. |
- Summary uses third-person indicative: *"Validates a pill recipe"*, not *"Validate"*.
- `# Errors` lists every way the function can fail, not just the common ones.
- `# Safety` is a contract: violation means undefined behaviour.
#### Constants & Statics
```rust
/// Maximum number of pills permitted in a single batch.
pub const MAX_BATCH_SIZE: u32 = 10_000;
```
- One `///` line stating what the value represents.
- Mention external constraints if relevant (*"Limited by the press die diameter."*).
---
### Inline Comments
Used for implementation detail - things a reader needs that don't belong in public API docs.(`//`)
#### Step Labels
Multi-phase functions label each phase with `// Step N: …`.
- Use only when the function has 2+ distinct phases.
- Each label sits on its own line immediately above the code it describes.
- Aim for 2–4 steps. If you need 8+, split the function.
#### Explanatory Comments
Place a `//` comment above any block whose purpose isn't obvious from the code.
```rust
// Convert the supplied name once and store its owned representation.
let name = name.into();
// The subtraction is safe because the quality inspector cannot reject more
// pills than were produced.
let accepted_count = requested_count
.checked_sub(rejected_count)
.expect("quality inspector returned more rejections than produced pills");
```
- Explain what and why - not how (the code already shows how).
- Place on the line immediately above the code, no blank line between.
- One comment per logical block; don't comment every line.
- Avoid restating the obvious: `// increment i` is noise.
---
### Safety Comments
Every `unsafe` block must be preceded by a `// SAFETY:` comment justifying
why the operations are sound.
```rust
// SAFETY: Disjoint per-pill access guaranteed by the single-threaded
// factory scheduler. Both slices are valid for the lifetime of the
// batch. The caller guarantees `inspection_results.len() ==
// acceptance_buffer.len()`, so unchecked indexing through
// `get_unchecked` and `get_unchecked_mut` is sound. Mutating
// `acceptance_buffer[index]` without atomics is safe because no
// other thread observes this batch's inspection data.
unsafe {
let count = inspection_results.len();
for index in 0..count {
let passed = *inspection_results.get_unchecked(index);
if passed {
*acceptance_buffer.get_unchecked_mut(index) += 1;
}
}
}
```
Every `SAFETY` comment must address the relevant safety dimensions:
| Category | Question the comment must answer |
|----------|----------------------------------|
| Aliasing | Why is there no overlapping `&mut` access? |
| Lifetime | Why are pointers/references valid for the duration of use? |
| Bounds | Why is unchecked indexing/pointer arithmetic within bounds? |
| Concurrency | Why are atomics unnecessary (or, if used, why is the ordering correct)? |
| Type validity | Why does the memory represent a valid instance of the target type? |
| Invariants | What caller guarantees or local invariants does this code rely on? |
- `// SAFETY:` uses UPPERCASE and a colon.
- It appears inside the function body, immediately before `unsafe {`.
- Written in prose, not bullet points.
- For `pub unsafe` functions, the `/// # Safety` section documents caller
obligations; the `// SAFETY:` inside the body documents why this
implementation satisfies them.
### Examples in Comments
Runnable `# Examples` sections in `///` doc comments are welcome - they
double as documentation and as compile-tested usage samples. While not
required for every item, they are especially valuable on key public types
and functions.
```rust
/// Coordinates inventory, manufacturing, and quality inspection.
///
/// Owns the ingredient inventory and quality inspector and orchestrates
/// batch production through the [`ProductionLine`] trait.
///
/// # Examples
///
/// ```
/// # use pill_factory::{PillFactory, PillRecipe, PillShape, ProductionLine};
/// # use pill_factory::inventory::IngredientInventory;
/// # use pill_factory::quality::QualityInspector;
/// let inventory = IngredientInventory::default();
/// let inspector = QualityInspector::new(/* … */);
/// let mut factory = PillFactory::new(inventory, inspector);
///
/// let recipe = PillRecipe::new("Aspirin", PillShape::Round, 100, 40, 10);
/// let report = factory.manufacture(&recipe, 1_000)?;
///
/// assert!(report.accepted_count() > 0);
/// # Ok::<(), anyhow::Error>(())
/// ```
pub struct PillFactory { /* … */ }
```
Rules:
- The example must compile - `cargo test` runs doc-tests by default.
- Use `# ` to hide setup lines (imports, helper construction) from the
rendered output while keeping them visible in the source.
- Keep examples minimal: construct one instance, call one method, assert one
outcome.
- If the example can't compile in a doc-test (e.g. references a fictional
crate path), wrap it in ` ```ignore` instead of ` ```rust`.
- The `# Examples` section goes after `# Errors` / `# Safety` (if present),
immediately before the item definition.
### Test Documentation
Every `#[test]` function carries a `///` doc comment with a fixed structure:
1. First line - states what the test verifies. Third-person indicative:
*"Tests that removing a component migrates the entity to a new archetype."*
2. `This test verifies that:` - bullet list of every condition under test.
Each bullet corresponds to an assertion or logical check in the test body.
3. `Expected results:` - bullet list of the concrete outcomes. These are
machine-checkable: every line should map to an `assert!` / `assert_eq!`.
```rust
/// Tests that removing a component migrates the entity to a new archetype.
///
/// This test verifies that:
/// - A component can be removed from an entity with multiple components
/// - The entity is migrated to a new archetype without the removed component
/// - Other components remain intact on the entity
/// - The old archetype is automatically cleaned up when empty
///
/// Expected results:
/// - remove_component returns Ok(())
/// - The entity still exists in entity_locations
/// - Only 1 archetype remains (the old one is deleted)
/// - The new archetype does not contain the removed component type
#[test]
fn entity_migrates_archetype_on_component_removal() { /* … */ }
```
Test helpers (preset constructors, builders) only need a one-line `///`
summary of what they create.
## Error Handling
### Recoverable Errors
Use `Result