Skip to Content
Comments

Comments in Rust

Comments let you leave notes in your code that the compiler completely ignores at runtime. Rust gives you three distinct types, each aimed at a different audience — yourself, your team, or automated documentation tools.

Types of Comments

Line Comments (//)

The most common comment in Rust. Everything from // to the end of the line is ignored by the compiler.

src/main.rs
fn main() {
    // price of one cutting chai in rupees
    let chai_price = 30; // per cup, not per pot
 
    // we order for two friends
    let cups = 2;
 
    // calculate subtotal using integer math
    let subtotal = chai_price * cups; // 60
    let total = subtotal + 5; // add 5 rupees for sugar extra
 
    println!("Total: {total}");
}
Total: 65

A few things to notice:

UsageExamplePurpose
Comment above a line// price of one cutting chaiExplains the intent of what follows
End-of-line comment// per cup, not per potAdds a quick unit or reminder
Multi-line thoughtRepeat // on each lineRust style prefers this over block comments

Rust style strongly favours // over /* */ for prose comments. Use // on consecutive lines for longer thoughts — it is easier to read and simpler to temporarily disable code.

Block Comments (/* ... */)

Rust supports C-style block comments. Unlike most languages, Rust block comments can be nested, which makes it safe to comment out code that already contains block comments.

src/main.rs
fn main() {
    let price = 100;
    let shipping = 20;
 
    /*
    let discount = 10;
    let coupon  = 5;
    let total   = price + shipping - discount - coupon;
    */
 
    let total = price + shipping;
    println!("Total: {total}");
}
Total: 120

Nested Block Comments

src/main.rs
fn main() {
    /* outer comment
        /* inner comment — valid in Rust! */
    still inside outer */
    println!("Block comments can be nested.");
}

Even though block comments are valid, the Rust community convention is to use // for nearly everything. Reserve /* */ for quickly disabling a chunk of code during debugging, then remove it before committing.

Documentation Comments (///)

Adding one extra slash turns a comment into documentation comment. Write it directly above a function, struct, enum, or trait, and cargo doc will turn it into a formatted HTML page.

src/main.rs
/// Returns the temperature in Fahrenheit.
///
/// Takes a Celsius value and applies the formula `F = C × 9/5 + 32`.
///
/// # Example
/// ```
/// let f = c_to_f(0);
/// assert_eq!(f, 32);
/// ```
fn c_to_f(celsius: i32) -> i32 {
    celsius * 9 / 5 + 32
}
 
fn main() {
    println!("{}", c_to_f(100)); // 212
}
212

Common /// Sections

Section headerPurpose
(opening paragraph)One-line summary of what the item does
# ArgumentsDescribe each parameter
# ReturnsDescribe the return value
# ExampleA runnable code snippet
# PanicsConditions under which the function panics
# ErrorsError variants returned in a Result

Code blocks inside # Example are run as tests when you execute cargo test. If your example compiles but produces a wrong result, the test will fail — keeping docs honest.

Module-Level Comments (//!)

Use //! (note the !) at the top of a file to document the file or crate itself, rather than the item that follows. These appear on the front page of your generated docs.

src/main.rs
//! # chai_calc
//! A tiny practice crate to learn Rust comments and arithmetic.
//!
//! This comment will appear on the front page of the generated docs.
 
/// Adds two integers and returns the result.
fn add(a: i32, b: i32) -> i32 {
    a + b
}
 
fn main() {
    println!("{}", add(3, 4)); // 7
}
7
Comment typeWritten asDocuments
Item doc comment///The function, struct, or enum immediately below
Inner doc comment//!The enclosing module or crate file

Comment Styles at a Glance

Good Comment Habits

HabitExample
Write why, not what// 5% tax is useful — // divide by 20 is not
Keep comments accurateAn outdated comment is worse than no comment
Use TODO / FIXME markers// TODO: add discount logic — editors highlight these
Remove dead code instead of commenting it out long-termCommented-out code ages badly and confuses readers

Rust does not treat TODO: or FIXME: as special keywords, but most editors and linters surface them automatically. They are a lightweight way to mark known gaps without creating a separate ticket.

Summary

TypeSyntaxAudienceVisible in Docs?
Line comment//You and your teamNo
Block comment/* ... */You and your team (temp use)No
Item doc comment///API consumers via rustdocYes
Crate/module doc comment//!API consumers via rustdocYes (front page)

What’s Next?

Now that you know how to annotate your code, you are ready to explore Control Flow — where you will learn how if expressions, loops, and match control the path your program takes at runtime.

Last updated on
Functions