Comments

Comments are notes in your source code that the compiler completely ignores. They exist purely for humans — you, and anyone else who reads your code later — to understand what’s going on.

Single-line comments

A double slash // comments out everything from that point to the end of the line.

CPP

int score = 0; // tracks the player's current score

Multi-line comments

Text wrapped between /* and */ can span multiple lines, which is useful for longer explanations or temporarily disabling a block of code.

CPP

/*
   This function calculates the average of all
   scores in the provided list and returns it
   as a floating-point value.
*/
double average(const std::vector<int>& scores) {
    // ...
}

/* */ comments cannot be nested

Writing `/* outer /* inner */ still outer */` does **not** work the way you might expect. The first `*/` closes the comment early, leaving `still outer */` as loose code that the compiler will try to parse — usually producing a confusing error. Stick to `//` for commenting out blocks that already contain `/* */` comments.

When to comment

The most valuable comments explain why something is done, not what is being done — the “what” should usually be clear from well-named variables and functions.

Explain non-obvious business logic or a tricky algorithm's intent.
Document why a workaround exists, especially for a compiler quirk or platform-specific bug.
Flag unfinished work with a consistent marker like // TODO: so it's easy to search for later.
Avoid restating exactly what the next line already says in plain English.

Documentation comments

For functions and classes meant to be used by other code, many C++ projects use Doxygen-style comments — a structured comment format starting with `/**` that documentation-generation tools can parse automatically to produce reference docs.

CPP

/**
 * Calculates the average of a list of scores.
 *
 * @param scores A list of integer scores. Must not be empty.
 * @return The arithmetic mean as a double.
 */
double average(const std::vector<int>& scores);

Good vs bad commenting

Not useful — restates the obvious

CPP

// increment i by 1
i++;

// set total to 0
int total = 0;

Useful — explains intent

CPP

// Skip index 0: it's a sentinel value reserved by the file format.
for (int i = 1; i < entries.size(); i++) {
    process(entries[i]);
}