Quick lesson before we get into the big stuff. Comments in Rust work about how you'd expect, but there's one feature — doc comments — that's genuinely worth knowing about early, because you'll see it in nearly every crate you ever depend on.
Regular comments
Two slashes start a line comment. There's no dedicated multi-line syntax that people actually use in practice — Rust developers just stack // on consecutive lines:
Rust does technically support /* block comments */, and they can even nest — but you'll rarely see them used outside of quickly silencing a chunk of code while debugging. Stick with // for anything you intend to keep.
Doc comments — comments that become documentation
Here's the part that's actually exciting. Use three slashes, ///, right above an item (a function, struct, enum — anything public), and that comment becomes part of your crate's official documentation, formatted with full Markdown support.
Run cargo doc --open in your project, and Cargo builds a full, searchable HTML documentation site from comments like this one — and opens it in your browser. This is exactly how the documentation on docs.rs gets generated for every crate published to crates.io. When you write a doc comment, you're writing the same kind of docs the entire ecosystem relies on.
Bonus: that code block inside the doc comment above isn't just for show — Cargo can actually compile and run it as a test, via
cargo test. Your documentation examples literally cannot go stale without your test suite telling you. We'll see this for real in the testing lesson.
Module-level docs with //!
There's a second flavor, //!, which documents the thing it's inside rather than the thing below it — typically placed at the very top of a file to describe what the whole module is for:
So... when should you actually write comments?
Here's the honest, slightly contrarian advice that experienced Rust developers tend to agree on: most comments are a sign that the code could be clearer. Before writing // adds 7% tax, consider whether fn add_sales_tax(price: f64) -> f64 would have made the comment unnecessary.
Comments earn their keep when they explain something the code can't say on its own:
- Why, not what — "we retry three times because the upstream API is flaky on Mondays" is gold; "loop three times" is noise.
- Non-obvious trade-offs or workarounds — "using a Vec here instead of a HashSet because we need to preserve insertion order."
- Anything a future reader (very possibly you, in six months) would otherwise have to reverse-engineer.
And reach for /// doc comments specifically on anything public that someone else — including future-you — will call without reading its source.
Quick exercise
Take the describe_temperature function from the functions lesson and give it a proper /// doc comment, including a short example block. Then run cargo doc --open and find your function in the generated site.
Short lesson, real payoff. Now let's get into the concept that makes Rust Rust — the one idea that, once it clicks, explains half the language's design decisions: ownership.