Complete Guide to Rust Comments

Table of Contents

Introduction to Comments in Rust

Comments are an essential part of any programming language, serving as documentation, explanations, and notes within your code. Rust provides several types of comments, each serving a specific purpose. Understanding how to use them effectively will make your code more maintainable and professional.

Why Comments Matter in Rust

Code Documentation: Explain complex logic and algorithms
Team Collaboration: Help other developers understand your code
Future Reference: Remind yourself why you made certain decisions
API Documentation: Generate beautiful documentation with rustdoc
Debugging: Temporarily disable code during development

1. Line Comments

Basic Line Comments

Line comments start with // and continue until the end of the line.

fn main() {
// This is a simple line comment
let x = 5; // This comment explains the variable
// Comments can be on their own line
// Or multiple lines like this
// Each line needs its own //
let y = 10; // You can also have code before a comment
// let z = 15; // This line is commented out (disabled)
println!("x = {}, y = {}", x, y);
}

Indentation and Alignment

fn calculate_discount(price: f64, percent: f64) -> f64 {
// Validate inputs
if price < 0.0 {
return 0.0; // Return 0 for invalid price
}
if percent < 0.0 || percent > 100.0 {
return price; // No discount for invalid percentage
}
// Calculate and return the discounted price
let discount = price * (percent / 100.0);
price - discount
// Aligned comments for similar lines
let a = 10;      // First value
let b = 20;      // Second value
let c = 30;      // Third value
}

2. Block Comments

Basic Block Comments

Block comments start with /* and end with */. They can span multiple lines.

fn main() {
/* This is a block comment
that spans multiple lines.
It's useful for longer explanations. */
let x = 5;
/* You can also use them inline */ let y = 10;
// Block comments can be nested /* like this */ but careful!
/* This is useful for temporarily disabling
large blocks of code during debugging:
let complex_calculation = perform_lengthy_computation();
process_results(complex_calculation);
*/
println!("x = {}, y = {}", x, y);
}

Documentation Block Comments

These are special block comments used for documentation (more on this later).

/**
* This is a documentation block comment.
* It's often used for module-level documentation.
* Each line typically starts with a * for readability.
*/
fn documented_function() {
// Function body
}

3. Doc Comments

Line Doc Comments (`///`)

Doc comments are used to generate documentation with rustdoc. They support Markdown formatting.

/// Represents a user in the system
///
/// # Examples
///
/// ```
/// let user = User::new("Alice", 30);
/// println!("User: {}", user.name);
/// ```
struct User {
/// The user's full name
name: String,
/// The user's age in years
age: u32,
/// Whether the user is active (comment on same line)
active: bool,
}
impl User {
/// Creates a new `User` with the given name and age.
///
/// # Arguments
///
/// * `name` - A string slice that holds the user's name
/// * `age` - The user's age
///
/// # Returns
///
/// A new `User` instance
///
/// # Panics
///
/// Panics if `age` is greater than 150
fn new(name: &str, age: u32) -> Self {
if age > 150 {
panic!("Age cannot be greater than 150");
}
User {
name: name.to_string(),
age,
active: true,
}
}
/// Returns a greeting from this user.
///
/// # Example
///
/// ```
/// let user = User::new("Bob", 25);
/// assert_eq!(user.greet(), "Hello, I'm Bob!");
/// ```
fn greet(&self) -> String {
format!("Hello, I'm {}!", self.name)
}
}

Inner Doc Comments (`//!`)

These provide documentation for the containing item (like modules or crates).

//! # My Crate
//!
//! `my_crate` is a collection of utilities for doing useful things.
//!
//! It provides:
//! - User management
//! - Data processing
//! - Utility functions
/// This module contains user-related functionality.
mod user {
//! User management module
//!
//! This module handles all user-related operations
//! including creation, authentication, and profile management.
pub struct User {
// ... fields ...
}
impl User {
// ... methods ...
}
}
// At the top of a file, this documents the entire module or crate
//! This module provides utility functions for string manipulation.
//!
//! # Overview
//! This module includes functions for:
//! - Trimming whitespace
//! - Converting case
//! - Splitting strings

Doc Comment Syntax Elements

/// # Headers
/// ## Level 2
/// ### Level 3
///
/// **Bold text** and *italic text*
///
/// - Bullet points
/// - Like this
///
/// 1. Numbered lists
/// 2. Also supported
///
/// [Links](https://rust-lang.org)
///
/// `inline code`
///
/// ```rust
/// // Code blocks with syntax highlighting
/// let x = 5;
/// println!("x = {}", x);
/// ```
///
/// > Blockquotes
/// > For important notes
///
/// | Tables | Are | Cool |
/// |--------|-----|------|
/// | col 1  | col2| col3 |
///
/// # Panics
/// This function panics if the input is invalid.
///
/// # Safety
/// This function is unsafe because...
///
/// # Examples
/// ```
/// // Example code that gets tested
/// assert_eq!(2 + 2, 4);
/// ```
fn documented_function() {}

4. Special Documentation Sections

Common Doc Comment Sections

/// # Panics
///
/// Documents conditions that will cause the function to panic.
///
/// # Examples
///
/// ```
/// // This example demonstrates usage
/// ```
///
/// # Errors
///
/// Documents error conditions for functions returning `Result`.
///
/// # Safety
///
/// Explains why a function is `unsafe` and what invariants must be upheld.
///
/// # Aborts
///
/// Documents conditions that abort the process.
///
/// # Undefined Behavior
///
/// Documents conditions that may cause undefined behavior.
fn complex_function() {}

Complete Documentation Example

//! # Data Processing Library
//!
//! A comprehensive library for processing and analyzing data.
//!
//! ## Features
//! - Fast data transformation
//! - Statistical analysis
//! - Export capabilities
use std::error::Error;
/// Represents a data point with a timestamp and value.
///
/// # Examples
///
/// ```
/// use my_lib::DataPoint;
///
/// let point = DataPoint::new(1625097600, 42.5);
/// assert_eq!(point.timestamp, 1625097600);
/// assert_eq!(point.value, 42.5);
/// ```
#[derive(Debug, Clone, PartialEq)]
pub struct DataPoint {
/// Unix timestamp (seconds since epoch)
pub timestamp: i64,
/// The actual value of the data point
pub value: f64,
}
impl DataPoint {
/// Creates a new `DataPoint`.
///
/// # Arguments
///
/// * `timestamp` - Unix timestamp (seconds since epoch)
/// * `value` - The data value
///
/// # Returns
///
/// A new `DataPoint` instance
///
/// # Examples
///
/// ```
/// let point = DataPoint::new(1625097600, 100.0);
/// ```
pub fn new(timestamp: i64, value: f64) -> Self {
DataPoint { timestamp, value }
}
/// Calculates the normalized value between 0 and 1.
///
/// # Arguments
///
/// * `min` - Minimum value in the dataset
/// * `max` - Maximum value in the dataset
///
/// # Returns
///
/// A normalized value between 0 and 1
///
/// # Panics
///
/// Panics if `min >= max`
///
/// # Examples
///
/// ```
/// let point = DataPoint::new(1625097600, 50.0);
/// let normalized = point.normalize(0.0, 100.0);
/// assert_eq!(normalized, 0.5);
/// ```
pub fn normalize(&self, min: f64, max: f64) -> f64 {
assert!(max > min, "max must be greater than min");
(self.value - min) / (max - min)
}
/// Processes multiple data points and returns statistics.
///
/// # Errors
///
/// Returns an error if the data slice is empty.
///
/// # Examples
///
/// ```
/// let points = vec![
///     DataPoint::new(1, 10.0),
///     DataPoint::new(2, 20.0),
///     DataPoint::new(3, 30.0),
/// ];
/// let stats = DataPoint::process_batch(&points).unwrap();
/// ```
pub fn process_batch(points: &[DataPoint]) -> Result<BatchStats, Box<dyn Error>> {
if points.is_empty() {
return Err("Empty dataset".into());
}
let sum: f64 = points.iter().map(|p| p.value).sum();
let mean = sum / points.len() as f64;
Ok(BatchStats {
count: points.len(),
sum,
mean,
min: points.iter().map(|p| p.value).fold(f64::INFINITY, f64::min),
max: points.iter().map(|p| p.value).fold(f64::NEG_INFINITY, f64::max),
})
}
}
/// Statistics for a batch of data points
#[derive(Debug)]
pub struct BatchStats {
/// Number of data points processed
pub count: usize,
/// Sum of all values
pub sum: f64,
/// Mean (average) value
pub mean: f64,
/// Minimum value
pub min: f64,
/// Maximum value
pub max: f64,
}

5. Attribute Comments

Documentation Attributes

// Suppress warnings about missing documentation
#![allow(missing_docs)]
// Mark this item as deprecated
#[deprecated(since = "1.2.0", note = "Use `new_function` instead")]
fn old_function() {}
// Include documentation from external file
#[doc(include = "path/to/docs.md")]
fn complex_feature() {}
// Hide from documentation
#[doc(hidden)]
pub fn internal_function() {}

Conditional Compilation Comments

// Only compile on debug builds
#[cfg(debug_assertions)]
fn debug_only_function() {
// Function body
}
// Only compile on release builds
#[cfg(not(debug_assertions))]
fn release_only_function() {
// Function body
}
// Platform-specific code
#[cfg(target_os = "windows")]
fn windows_specific() {
println!("Running on Windows");
}
#[cfg(target_os = "linux")]
fn linux_specific() {
println!("Running on Linux");
}
// Feature-gated code
#[cfg(feature = "advanced")]
fn advanced_feature() {
// Advanced functionality
}

6. TODOs and FIXMEs

Common Comment Tags

fn main() {
// TODO: Implement error handling
// FIXME: This algorithm is inefficient for large datasets
// XXX: This code is temporary and should be refactored
// HACK: This works but needs a better solution
// OPTIMIZE: This loop is slow
// REVIEW: Double-check this logic
// NOTE: This assumes input is always valid
// WARNING: This code is experimental
// TODO(#123): Reference issue numbers
// FIXME(john): Assign to specific person
// BUG: This crashes when input is empty
// PERF: This allocation could be avoided
// SECURITY: This exposes sensitive data
// DEPRECATED: Use new API instead
}

Organized TODO System

// TODO: [Priority: High] Add authentication
// TODO: [Priority: Medium] Improve error messages
// TODO: [Priority: Low] Add more examples
// TODO: [Category: API] Version 2 endpoint
// TODO: [Category: UI] Dark mode support
// TODO: [Category: Tests] Add integration tests
// TODO: [Owner: Alice] Review database schema
// TODO: [Owner: Bob] Update documentation
// TODO: [Due: 2024-03-01] Release preparation
// TODO: [Due: Next Sprint] Performance optimization

7. Code Documentation Best Practices

What to Comment

/// BAD: Redundant comment
let x = 5; // Sets x to 5
/// GOOD: Explains why
let timeout_seconds = 30; // AWS API timeout (max allowed)
/// BAD: Obvious
// Add two numbers
fn add(a: i32, b: i32) -> i32 { a + b }
/// GOOD: Explains non-obvious behavior
/// 
/// # Panics
/// Panics if the sum would overflow i32
fn add(a: i32, b: i32) -> i32 {
a.checked_add(b).expect("Integer overflow")
}

Documentation Examples

/// Processes a list of numbers and returns statistics.
///
/// This function is optimized for small lists (< 1000 elements).
/// For larger lists, use [`process_batch`] which is more efficient.
///
/// # Arguments
///
/// * `data` - A slice of f64 values to process
///
/// # Returns
///
/// A tuple containing (min, max, mean, median)
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// let data = vec![1.0, 2.0, 3.0, 4.0, 5.0];
/// let (min, max, mean, median) = process_small_list(&data);
/// assert_eq!(min, 1.0);
/// assert_eq!(max, 5.0);
/// ```
///
/// Handling empty lists:
///
/// ```
/// let data: Vec<f64> = vec![];
/// let result = process_small_list(&data);
/// assert_eq!(result, None);
/// ```
///
/// # Panics
///
/// This function will panic if any value is NaN.
///
/// # See Also
///
/// - [`process_batch`] for large datasets
/// - [`normalize_data`] for data normalization
pub fn process_small_list(data: &[f64]) -> Option<(f64, f64, f64, f64)> {
if data.is_empty() {
return None;
}
let min = data.iter().fold(f64::INFINITY, |a, &b| a.min(b));
let max = data.iter().fold(f64::NEG_INFINITY, |a, &b| a.max(b));
let mean = data.iter().sum::<f64>() / data.len() as f64;
// Calculate median
let mut sorted = data.to_vec();
sorted.sort_by(|a, b| a.partial_cmp(b).unwrap());
let median = if sorted.len() % 2 == 0 {
(sorted[sorted.len() / 2 - 1] + sorted[sorted.len() / 2]) / 2.0
} else {
sorted[sorted.len() / 2]
};
Some((min, max, mean, median))
}

8. Module-Level Documentation

Organizing Module Documentation

//! # Networking Module
//!
//! Provides HTTP client and server functionality with async support.
//!
//! ## Architecture
//!
//! The module is organized into three main components:
//! - `client`: HTTP client implementation
//! - `server`: HTTP server implementation
//! - `types`: Common types and traits
//!
//! ## Examples
//!
//! ### Creating a client
//!
//! ```rust
//! use networking::Client;
//!
//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
//! let client = Client::new();
//! let response = client.get("https://api.example.com").await?;
//! println!("Status: {}", response.status());
//! # Ok(())
//! # }
//! ```
//!
//! ## Feature Flags
//!
//! - `rustls`: Use rustls instead of native TLS (default)
//! - `http2`: Enable HTTP/2 support
//! - `websocket`: Include WebSocket support
//!
//! ## Performance Notes
//!
//! The module uses connection pooling and automatic keep-alive
//! for optimal performance. Configure pool size with `POOL_SIZE`
//! environment variable.
//!
//! ## Security Considerations
//!
//! - TLS 1.3 is enabled by default
//! - Certificate validation is strict
//! - Timeouts are configured for all operations
pub mod client;
pub mod server;
pub mod types;

9. Testing Documentation Examples

Doc Tests

/// Adds two numbers together.
///
/// # Examples
///
/// ```
/// use my_crate::add;
///
/// let result = add(2, 3);
/// assert_eq!(result, 5);
/// ```
///
/// The examples are automatically tested by `cargo test`.
/// This ensures documentation stays accurate.
///
/// ```rust
/// // This example should panic
/// use my_crate::add;
/// 
/// // This would overflow i32
/// // add(std::i32::MAX, 1);
/// ```
///
/// ```rust,should_panic
/// // This example is expected to panic
/// use my_crate::add;
/// add(std::i32::MAX, 1); // Should panic on overflow
/// ```
///
/// ```rust,ignore
/// // This example won't be tested (ignored)
/// // Useful for incomplete examples
/// ```
///
/// ```rust,no_run
/// // This example compiles but doesn't run
/// // Useful for code that would run forever
/// loop {
///     println!("Running...");
/// }
/// ```
pub fn add(a: i32, b: i32) -> i32 {
a + b
}

10. IDE Integration and Tooling

Comment Annotations for IDEs

// This comment helps IDEs provide better code insight
// The following annotations are commonly supported:
// MARK: - Section Name (Xcode style)
// FIXME: This needs to be fixed (most IDEs highlight this)
// TODO: Implement this (most IDEs highlight this)
// NOTE: Important information (some IDEs highlight this)
// OPTIMIZE: Performance bottleneck (some IDEs highlight this)
// Some IDEs also support:
// #region Region Name (Visual Studio style)
// #endregion
// And:
// <editor-fold desc="Description">
// </editor-fold> (IntelliJ style)

Generating and Viewing Documentation

# Generate HTML documentation
cargo doc
# Generate and open in browser
cargo doc --open
# Generate documentation for all dependencies
cargo doc --open --all-features
# Check documentation without generating
cargo doc --no-deps
# Test documentation examples
cargo test --doc
# Document private items as well
cargo doc --document-private-items

11. Advanced Comment Techniques

Conditional Compilation with Comments

// This code is only included in debug builds
#[cfg(debug_assertions)]
fn debug_assertions_enabled() {
println!("Debug assertions are enabled");
// These comments help track debug-only features
// DEBUG: Verbose logging enabled
// DEBUG: Extra validation active
}
// This code is only included in release builds
#[cfg(not(debug_assertions))]
fn release_mode() {
println!("Running in release mode");
// OPTIMIZE: All optimizations enabled
// SAFETY: Bounds checks removed
}

Comment-Based Code Generation

// Some build scripts and macros use comments for code generation
/// #[derive(Debug)]
/// This comment is read by a procedural macro
#[derive(Debug)]
struct MyStruct {
field: i32,
}
// Comments can be used with macros
macro_rules! create_function {
($func_name:ident) => {
/// This function is generated by a macro
/// # Examples
/// ```
/// create_function!(foo);
/// foo();
/// ```
fn $func_name() {
println!("Function {:?} called", stringify!($func_name));
}
};
}
create_function!(foo);

12. Common Patterns and Anti-patterns

Good Comment Patterns

/// GOOD: Explains the "why" not the "what"
fn calculate_interest(principal: f64, rate: f64, years: i32) -> f64 {
// Using compound interest formula: A = P(1 + r)^t
// This matches the bank's calculation method
principal * (1.0 + rate).powi(years)
}
/// GOOD: Documents assumptions
fn process_data(data: &[u8]) -> Vec<u8> {
// Assumes data is UTF-8 encoded and less than 1MB
// The caller guarantees this in the documentation
data.to_vec()
}
/// GOOD: Warns about side effects
fn modify_global_state() {
// WARNING: This modifies global configuration
// All running threads will be affected
unsafe {
GLOBAL_CONFIG = new_config;
}
}

Bad Comment Patterns

/// BAD: Obvious comments
let x = 5; // Set x to 5
x = x + 1; // Add 1 to x
/// BAD: Outdated comments
// Now uses new API (from 2 years ago, but API changed again)
fn old_comment() {}
/// BAD: Misleading comments
// This function never fails (but it can panic)
fn might_fail() {
panic!("Actually, it can fail");
}
/// BAD: Commented-out code without explanation
// let old_implementation = something;
// if condition {
//     do_something();
// }
/// BAD: Too many comments
fn simple_function() {
// Start function
// Declare variable
let x = 5;
// Print variable
println!("{}", x);
// End function
}

Conclusion

Rust's comment system is comprehensive and integrated with the language's tooling:

Key Takeaways

Line Comments (//) - For quick notes and code explanation
Block Comments (/* */) - For multi-line explanations and disabling code
Doc Comments (///, //!) - For generating API documentation
Doc Attributes - Control documentation generation
Special Tags - TODO, FIXME, NOTE for tracking tasks
Doc Tests - Ensure documentation examples stay correct

Best Practices

Comment the why, not the what
Keep comments up-to-date with code changes
Use doc comments for public API documentation
Write examples that actually compile and run
Use cargo doc to check documentation quality
Follow Rust's documentation conventions

Tools

cargo doc - Generate documentation
cargo test - Test documentation examples
rustdoc - The documentation generator
IDE plugins - Enhanced comment support

Well-written comments and documentation make your Rust code more maintainable, usable, and professional. The Rust community places high value on good documentation, making it an essential skill for Rust developers.