Chapter 6: Rust Comments
Rust Comments
Comments are one of the simplest but most useful parts of any language. In Rust, comments are extra text in your code that the compiler completely ignores — they exist only to help humans (you, your teammates, future you in 2027 😄) understand what the code does, why it does it, and sometimes how it works.
Rust has two main categories of comments:
- Regular comments (just notes, ignored by everyone except humans)
- Documentation comments (special magic — they turn into beautiful auto-generated docs when you run cargo doc)
Let me explain everything slowly, like we’re sitting together debugging code over biryani, with tons of examples you can copy-paste and try.
1. Regular Comments (The Everyday Ones)
These are for quick notes inside code. Rust supports two styles (like C/C++/JavaScript).
A. Line Comments — // (Most common & idiomatic in Rust)
- Starts with //
- Everything after // on the same line is ignored
- Very clean, short explanations
|
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
fn main() { // This is a single-line comment explaining the next line let temperature = 32; // Current temp in Hyderabad today (Feb 2026) // You can put it at the end of a line too println!("It's {}°C — perfect for learning Rust!", temperature); // Output message // Multiple lines? Just start each with // // Line 1 of explanation // Line 2 of explanation // Line 3... } |
Run cargo run — comments disappear, only output shows.
B. Block Comments — /* … */ (Less common, but useful)
- Starts with /*
- Ends with */
- Can span multiple lines
- Can be nested (very rare feature — most languages don’t allow this!)
|
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
fn main() { /* This is a block comment. It can go across many lines. Useful for temporarily disabling big chunks of code. */ println!("Hello!"); /* You can even nest them! /* Like this inner one */ Still part of outer block */ } |
Tip from teacher: Rust community prefers // line comments almost always. Block comments are mostly used to comment out large sections during debugging (like /* code here */ to disable temporarily).
2. Documentation Comments (The Powerful Ones — Rust’s Superpower)
These are special — they use extra slashes/asterisks so rustdoc (the built-in documentation generator) can read them and create HTML docs automatically.
There are four kinds, but really two pairs:
- Outer doc comments → document the thing that comes after them (function, struct, module, etc.)
- Inner doc comments → document the thing that contains them (the module or crate itself)
Outer Documentation (Most Common — You See This Everywhere)
- Line style: /// (three slashes)
- Block style: /** … */ (two asterisks)
|
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
/// Adds two numbers and returns the result. /// /// # Examples /// /// ``` /// let sum = add(5, 7); /// assert_eq!(sum, 12); /// ``` fn add(a: i32, b: i32) -> i32 { a + b // No semicolon = implicit return } /** * This is a block-style outer doc comment. * It works the same as /// * Markdown is supported here too! */ struct User { name: String, age: u32, } |
Notice:
- Markdown support! You can write headings #, code blocks
`, lists, links, etc. - Sections like # Examples, # Panics, # Errors are conventional — cargo doc formats them nicely.
Inner Documentation (Used for modules & crates)
- Line style: //! (exclamation after two slashes)
- Block style: /*! … */
These go inside the thing they describe (usually at the top of a file or module).
|
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
//! This is the main documentation for the entire crate. //! //! We are learning Rust comments in Hyderabad, 2026. //! //! # Quick Start //! Run `cargo run` to see output. fn main() { println!("Inner docs describe the containing item!"); } |
In src/lib.rs (for libraries), you see //! at the very top a lot — it documents the whole crate.
3. Real-World Example — Mix Everything
Create a small file and try this:
|
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 |
//! Learning Rust Comments — Webliance's Tutorial //! Hyderabad, Telangana - Feb 26, 2026 /// Calculates if today is hot in Hyderabad. /// /// Returns `true` if temperature > 30°C. fn is_hot(temp_c: f32) -> bool { // Simple check — no fancy logic here temp_c > 30.0 /* We could add more logic later, like humidity factor, but not now */ } fn main() { let current_temp = 32.5; // Quick debug note println!("Current temp: {}°C", current_temp); if is_hot(current_temp) { println!("It's summer time! 🔥"); } else { println!("Nice weather to code ☀️"); } } |
Now run:
|
0 1 2 3 4 5 6 |
cargo doc --open |
→ It opens your browser with beautiful HTML docs for is_hot (with examples if you add them), and crate-level docs from //!.
Quick Teacher Summary Table
| Type | Syntax | What it documents | Use Case | Markdown? |
|---|---|---|---|---|
| Regular line | // | Nothing (just note) | Quick explanations | No |
| Regular block | /* … */ | Nothing | Disable code chunks, long notes | No |
| Outer doc line | /// | Next item (fn, struct…) | Function/struct/module docs | Yes |
| Outer doc block | /** … */ | Next item | Same as /// but multi-line | Yes |
| Inner doc line | //! | Containing item (module/crate) | Crate overview, module intro | Yes |
| Inner doc block | /*! … */ | Containing item | Rare, same as //! | Yes |
Best practices in 2026 Rust community:
- Use // for normal notes
- Use /// above almost everything public (functions, structs, etc.)
- Add # Examples in doc comments — hugely helpful!
- Run cargo doc –open often — see your docs live
- Avoid block comments /* */ unless disabling code
Comments make code readable — good comments make it maintainable forever.
Want to go deeper?
- How to write great doc comments with Markdown?
- Generate & publish docs to docs.rs?
- Or move to input (so program can read from user)?
Just tell me — class is still in session! 🦀🚀
