# 1.2 Comments

> Rust comments: // and /* */ syntax, what to comment and why, and commenting out code.

Source: https://learnrust.net/chapter-1/comments/

A **comment** is a programmer-readable note placed directly in the source code. The compiler ignores comments completely; they exist for humans only.

## Comment syntax

A line comment starts with `//` and runs to the end of the line:

```rust
fn main() {
    // This whole line is a comment.
    println!("Hello!"); // So is everything after the slashes here.
}
```

Comments on their own line conventionally sit directly *above* the code they describe, indented to match. Comments at the end of a code line are best kept short; if it doesn't fit comfortably, move it above.

For longer notes there are block comments, which run from `/*` to `*/` and can span lines:

```rust
/* This is a block comment.
   It keeps going until the closing marker,
   which is here: */
fn main() {
    println!("Hello!");
}
```

In practice, Rust code leans almost entirely on `//`, even for multi-line notes (each line just gets its own `//`). Your editor will happily add or remove the slashes on a whole selection at once, which removes most of the reason block comments exist.

{% callout(kind="tip", title="Tip") %}
Unlike in C and many other languages, Rust block comments nest: `/* outer /* inner */ still a comment */` works, because the compiler tracks the pairs. You can wrap a block comment around code that already contains one. It's a small kindness, and a preview of a theme: where Rust's designers could remove a classic annoyance, they usually did.
{% end %}

One more marker, for completeness: you'll sometimes see comments starting with three slashes, `///`. Those are **documentation comments**, and they do something extra; lesson 13.7 covers them. Until then, two slashes.

## What to comment

Knowing the syntax is the easy half. Knowing what's worth saying is the half that makes comments useful, and there's a hierarchy worth internalizing.

At the top of a program or a section, comments should say **what** the code does, so a reader can orient without reading any code:

```rust
// Deals each player a starting hand and scores the opening round.
```

Inside the code, comments should say **how** a non-obvious approach works, at the level of strategy rather than play-by-play:

```rust
// To find the winner in one pass, we track the best score seen so far
// and replace it whenever a player beats it.
```

And at the level of an individual statement, the best comments say **why** the code does what it does, because the code already says what it does. Compare:

```rust
let sight = 0; // set sight to 0
```

```rust
let sight = 0; // the player drank the blindness potion this turn
```

The first comment is noise; it restates the code while explaining nothing. The second carries information that exists nowhere else in the program. If you only remember one rule about commenting, make it this one: the code says *what*, the comment says *why*.

{% callout(kind="best", title="Best practice") %}
Comment as if writing to someone who has no idea what the code does, because that someone is you, several months from now. Code you wrote recently always feels too obvious to need comments. That feeling has betrayed every programmer who has ever trusted it.
{% end %}

## Commenting out code

Comments have a second job: temporarily disabling code. Putting `//` in front of a statement makes the compiler skip it, which is useful surprisingly often. You'll comment code out to test the rest of the program without one piece running, to keep a half-written section from breaking the build, or to try a new approach while keeping the old one around for reference.

```rust
fn main() {
    println!("This prints.");
    // println!("This doesn't.");
}
```

Editors make this a single keystroke on whole blocks of selected lines (`Ctrl+/` in VS Code, `Cmd+/` on a Mac). One caution from lesson [0.11](@/chapter-0/warnings-lints-and-clippy.md)'s spirit: commented-out code left behind permanently becomes clutter that confuses future readers. Disable freely while working, then clean up.

## Quiz time

**Question #1**

What does the compiler do with comments?

<details class="solution">
<summary>Show solution</summary>

Nothing. They're stripped out before the code is analyzed; comments exist purely for human readers.

</details>

**Question #2**

This comment restates its code. Rewrite it into the kind of comment this lesson recommends (invent any plausible reason you like):

```rust
let cost = items * 2 * price; // multiply items by 2 and by price
```

<details class="solution">
<summary>Show solution</summary>

Say *why*, not *what*. For example:

```rust
let cost = items * 2 * price; // these items are only sold in pairs
```

Any comment that explains the reason for the `* 2` (instead of narrating it) is a good answer.

</details>

**Question #3**

You want to test your program with one statement disabled. What's the quickest way?

<details class="solution">
<summary>Show solution</summary>

Comment it out: put `//` in front of it (most editors toggle this with `Ctrl+/` or `Cmd+/`), run your test, then remove the slashes.

</details>

Comments describe programs to people. Next, we start on the thing programs themselves are mostly about: data, and the variables that hold it.