Comments, rustfmt & Clippy

Syntax

// A line comment: ignored by the compiler.

/* A block comment,
   which can span lines. */

/// A doc comment: documents the item that follows it.
/// It supports Markdown.
fn add(a: i32, b: i32) -> i32 {
    a + b
}

• // — ordinary comments. Explain why code does something; the code itself shows what.
• /* ... */ — block comments. They're rarely used in Rust code.
• /// — doc comments for the item below them (function, struct, enum, …). cargo doc --open turns them into an HTML documentation site, the same format as the standard library's docs.
• //! — doc comments for the enclosing file or crate, usually at the top of main.rs or lib.rs.

rustfmt: automatic formatting

cargo fmt           # format every file in the project
cargo fmt --check   # report unformatted files without changing them

rustfmt rewrites your code into the standard Rust style: 4-space indentation, consistent spacing, and line breaks for long lines. Nearly every Rust project uses it, so all Rust code looks familiar. Run it often — or enable format on save in your editor — and use --check in CI.

Clippy: the Rust linter

cargo clippy

Clippy checks for hundreds of common mistakes and non-idiomatic patterns that aren't compile errors. For example, this compiles fine:

let ready = true;
if ready == true {
    println!("Ready");
}

but cargo clippy reports:

warning: equality checks against true are unnecessary
 --> src/main.rs:3:8
  |
3 |     if ready == true {
  |        ^^^^^^^^^^^^^ help: try: `ready`

Each warning names the lint and links to an explanation. Treat Clippy warnings as free code review from experienced Rust developers. (rustfmt and Clippy come with a standard rustup installation; if they're missing, run rustup component add rustfmt clippy.)

Example

//! A tiny temperature converter.

/// Converts a temperature from Celsius to Fahrenheit.
///
/// Uses the formula `F = C × 9 / 5 + 32`.
fn celsius_to_fahrenheit(celsius: f64) -> f64 {
    celsius * 9.0 / 5.0 + 32.0
}

fn main() {
    // Water boils at 100 °C at sea level.
    let boiling = celsius_to_fahrenheit(100.0);
    println!("Boiling point: {boiling}°F");
}

Expected output

Boiling point: 212°F

Common mistakes

• Writing /// where nothing follows it. A doc comment must sit directly above an item; at the end of a block the compiler reports error[E0585]: found a documentation comment that doesn't document anything.
• Commenting what obvious code does (// add one to x above x += 1). Save comments for intent, trade-offs, and surprises.
• Arguing about formatting in code review. Let cargo fmt decide.
• Ignoring Clippy's suggestions without reading them — many point to real bugs or simpler code.

Practice

Take this function, add a /// doc comment explaining what it does, and add a // comment inside explaining the formula. Then call it and print Area: 12.

fn area(width: u32, height: u32) -> u32 {
    width * height
}

/// Returns the area of a rectangle with the given width and height.
fn area(width: u32, height: u32) -> u32 {
    // A rectangle's area is its width multiplied by its height.
    width * height
}

fn main() {
    println!("Area: {}", area(3, 4));
}