Rust — Comments

Three comment forms

// 1. Line comment — everything after // on this line is ignored

/* 2. Block comment — spans
   multiple lines */

/// 3. Doc comment — documents the item BELOW it

Line comments — the daily driver

let max_retries = 3;   // payment API drops ~1% of requests silently

Use them to explain why, not what:

// WRONG: restates the obvious
let width = 10; // width is 10

// RIGHT: captures the invisible reason
let width = 10; // matches the design spec's fixed sidebar

Block comments — with a superpower

Unlike most languages, Rust block comments nest:

/* outer
   /* inner — still inside */
   still commented out! */
fn main() {}

This makes temporarily disabling code containing block comments painless (a real weakness in C/Java).

Doc comments — /// and //!

Triple-slash comments attach to the item that follows and become official documentation:

/// Converts Celsius to Fahrenheit.
///
/// # Examples
///
/// ```
/// assert_eq!(to_fahrenheit(100.0), 212.0);
/// ```
pub fn to_fahrenheit(celsius: f64) -> f64 {
    celsius * 9.0 / 5.0 + 32.0
}

What they give you:

1. Editor hovers — VS Code/rust-analyzer show this text on every call site
2. cargo doc — generates a full HTML documentation site:

$ cargo doc --open

3. Doctests — code blocks in ``` ticks inside the comment are compiled and run by cargo test. Your examples can never rot.

Markdown works inside doc comments

/// ## Panics
///
/// Panics if `index` is out of bounds.
///
/// See also: [`clamp`]

Headings, lists, links to other items in brackets — all standard.

Inner doc comments — //!

Rare but real: //! documents the enclosing file/module itself (placed at the very top):

//! Utilities for parsing config files.
//!
//! Everything here assumes UTF-8 input.

Comment etiquette for Rust teams

// ✓ WHY comments, TODOs, safety notes:
// SAFETY: ptr is valid because caller guarantees non-null
unsafe { *ptr = 0 };

// ✓ TODO with context:
// TODO(#142): remove after Safari 17 ships fix

// ✗ Never narrate mechanics:
i += 1; // add one to i

SAFETY: is a community convention specifically marking unsafe blocks — reviewers will demand it.

Mini Practice

1. Write a function with a /// doc comment including an example block.
2. Run cargo test — watch your doctest execute.
3. Generate docs with cargo doc --open; find your function.
4. Test nested block comments; compare with JavaScript's behavior.

Next: variables →