2.4 Comments

Comments are used in almost every programming language there is, and are used as a means of keeping track of what piece of code does what in you code. As they’re only there to help the programmer—or programmers—understand their code better, comments are automatically removed upon compile time. This means comments do not affect the final outcome of your program, but are rather there to serve as little notes to yourself.

At tech companies it’s almost always required to write comments—because not only you, but also others— will have an easier time understanding your code. Commenting is thus good both for you and others, in order to know what pieces of logical operations do what.

There’s no difference between comments in Rust and those of other languages—the real difference is how they’re written—and even then, there are many languages where comments look identical to that of Rust’s. Depending on how you look at it, there are two—or three—different types of comments in Rust: line comments and doc comments.

Line comments

This type of comment is the most common one—they should be written anywhere you see fit. Whenever there’s a logical operation you may forget about in the future, or a piece of code that you may not pay as much attention to for a while: write a comment!

Commenting is also a useful method to remember what things do what over extended periods of time. Work in a project a day, you may need no comments, but work in it for a years, you’re definitely going to need comments!

Line comments are written using two slashes ‘//’:

// The following message prints a message to the console
println!("Hello, world!");

Everything subsequent to the slashes, as well as the slashes themselves, are removed by the compiler upon being compiled—meaning you can put absolutely anything you want after the slashes. It can—however—complicate things if you’re unclear inside the comment as to what the code below it does. Comments can be extremely confusing if used in a non-clever way.

Since it’s everything subsequent to the slashes as well as the slashes themselves that gets removed, we can also write line comments on the same line as a fully functioning piece of code:

println!("Hello, world!"); // Prints a message to the console

It’s completely up to you to choose what comment goes where—whether you feel like putting comments on its own line, or have them followed by an expression or statement.

Doc comments

As the name quite clearly suggests, this type of comment is used for writing doc comments—that is, comments for a documentation. Should you be unfamiliar with what a documentation is, feel free to have a quick look at Rust’s official documentation and notice how it contains all the different functions you may access using the standard library.

When you’re working on your own libraries—a library you or others may reuse in binary projects—it’s kind to generate that library’s own documentation. Doc comments get placed in a similar fashion to how the information in Rust’s documentation looks upon generating a documentation out of your project. For that reason, it’s important we provide our libraries with as much information as we possibly can.

Doc comments should be written on top of every function, explaining in-depth what sthat particual function does. A doc comment is written using three slashes at the side of each other ‘///’, rather than two of them ‘//’:

/// Move sheep specified amount of dimensions.
///
/// # Examples
///
/// ```
/// move_sheep(12);
/// ```
fn move_sheep(n: i32)
{
    // Crazy things happening in here.
}

Holy Piñata, look at how many dimensions we moved that sheep!

It’s recommended to provide your doc comments with as many examples as you possibly can—so that others using your functions can easily know how they’re supposed to be used.

Overall functionality doc comments

There is another type of doc comment—written using two slashes and an exclamation mark ‘//!’—that you use when commenting on the overall functionality of a specific library. At the very start of a file, or at the start of a whole new application, you use these comments to explain what application or library as a whole does, as well as what functionality it has to offer—if you wanted to, you could even contain some information regarding the copyright of your code:

//! This library is used when fishing in the ocean
//! and you’re way too lazy to really fish.
//! Do steal this code, plzzzzzz... ← “yes, this code is sleepy”

Keep in mind to be as thorough as possible whenever you write comments—and do stay on subject!

Exercises

  • Make a promise unto yourself to use comments as often as you possibly can.

Moreover

As stated earlier, the usage of comments is a wonderful way to keep track of what your code does—and by that, keeping it clean. Sometimes when commenting, you may also realize things about your code that you otherwise wouldn’t have realized. Perhaps there’s something you could’ve done in a different way?