What comments are
A comment is text in your source code that the compiler ignores completely. It does not run, it does not print, and it does not change what the program does. Comments exist for people: they explain what a piece of code is for, why a decision was made, or what a later reader should watch out for.
Rust has two ways to write one.
Single-line comments
Type // and everything from there to the end of the line is ignored:
// Next line will greet the user:
println!("Hello user!");
Hello user!
The comment ends by itself at the end of the line, so the next line is ordinary code again. You can also put a comment after code on the same line:
println!("Hello user!"); // This line greets the user
println!("This is not a comment!");
Hello user!
This is not a comment!
Only the part after // is ignored. The println! before it still runs.
Block comments
To comment out several lines at once, start with /* and finish with */. Everything between the two markers is ignored, however many lines it covers:
/* This is a
multi-line comment
println!("This will not run");
Next line will greet the user:
*/
println!("Hello user!");
Hello user!
Notice that the println! inside the comment does not run. Turning code into a comment to stop it from running, without deleting it, is called commenting out. It is a common way to test a program with and without a line.
Rust block comments can nest
Unlike in some other languages, a block comment can contain another block comment in Rust, and the outer one ends only at the matching */:
/* outer /* inner */ still a comment */
println!("nested ok");
nested ok
This makes it safe to comment out a stretch of code that already contains block comments. The flip side is that every /* needs its own */. A block comment that is never closed is a compile error: "unterminated block comment".
Comment markers inside strings
Inside a string literal, // and /* are just characters:
println!("// this is text, not a comment");
// this is text, not a comment
Documentation comments
Rust has a third kind, written with three slashes: ///. It documents the item right below it, such as a function, and tools can turn these comments into documentation pages. To the compiler it is still a comment, and it doesn't change how the program runs. For now, plain // is all you need.
Good and bad comments
- Explain why, not what. A comment such as
// add one to countabovecount += 1;repeats the code. A comment that says why the count must increase here tells the reader something the code can't. - Keep comments up to date. A comment that no longer matches the code is worse than none.
- Don't rely on comments to excuse unclear code. Good names for variables and functions often remove the need for a comment.
Common mistakes
- Using
#for comments. That is how some other languages do it. In Rust,#begins an attribute such as#[derive(Debug)], not a comment. - Printing instead of commenting. Writing
println!("Story of Andy")prints the text, so it shows up in the output. A comment must start with//so that nothing is printed. - Forgetting that
//comments end at the line break. A second line of explanation needs its own//. - Leaving a block comment open. If a
/*has no matching*/, the compiler reports an error instead of ignoring the rest of the file.
The lesson's exercise
The exercise gives you a short program of println! lines that tell a story, starting with:
println!("My name is Andy");
println!("I started coding at 15 years old");
and asks you to document it by adding a comment on line 1, above the existing lines, that says Story of Andy. Do it in two steps:
- Start the line with
//, which tells Rust to ignore the rest of the line. - Write the text after it:
// Story of Andy.
Do not wrap the text in println!, since the goal is a note for readers, not extra output. The program prints the same lines as before.
Key takeaways
- Comments are ignored by the compiler and exist for human readers.
//comments out the rest of the line./* ... */comments out everything between the markers, over any number of lines, and can nest.- Comment markers inside a string are plain text.
- Comments should explain why the code does something, not repeat what it says.
