C++ Comments: Single-Line, Multi-Line and Writing Good Comments

A comment is text in your source code that the compiler ignores. Comments are for people: they explain why the code does something, warn about traps, and help you (or a teammate) understand the code months later.

Single-line comments: //#

Everything after // until the end of the line is a comment:

#include <iostream>

int main() {
    // Print a welcome message
    std::cout << "Welcome!\n";

    int seats = 40;  // the hall has 40 seats
    std::cout << seats << " seats\n";
}

Welcome!
40 seats

A comment can stand on its own line or follow code on the same line.

Multi-line comments: /* */#

Text between /* and */ is a comment, even across several lines:

#include <iostream>

int main() {
    /*
       Ticket price rules:
       - children under 12 pay half
       - everyone else pays full price
    */
    int full_price = 200;
    std::cout << full_price / 2 << '\n';
}

100

Multi-line comments cannot be nested: the first */ ends the comment, even if there was another /* inside it. For that reason, many programmers use // on every line, even for longer comments.

Commenting out code#

While testing, you can disable a line by turning it into a comment, without deleting it:

#include <iostream>

int main() {
    std::cout << "Step 1\n";
    // std::cout << "Step 2\n";
    std::cout << "Step 3\n";
}

Step 1
Step 3

Most editors toggle comments with Ctrl + / (Cmd + / on macOS). Remove commented-out code before you share it; version control (such as Git) keeps the old versions for you.

Documentation comments#

Comments placed just before a function often describe what it does, its parameters and its result. Tools such as Doxygen can turn comments written with /// or /** */ into documentation:

/// Returns the area of a rectangle.
/// @param width  the width, in metres
/// @param height the height, in metres
double area(double width, double height) {
    return width * height;
}

Writing good comments#

Explain the why, not the what. The code already says what it does:

// Bad: repeats the code
count = count + 1;  // add 1 to count

// Good: explains the reason
count = count + 1;  // include the header row in the total

Good comments:

• explain decisions, assumptions and business rules;
• warn about surprising behaviour or edge cases;
• mark unfinished work with a searchable tag, such as // TODO: handle negative values.

If you need a comment to explain what a confusing line does, first try to make the code clearer, for example by choosing a better variable name.

Common mistakes#

Practice#

#include <iostream>

int main() {
    std::cout << "Loading data\n";
    std::cout << "Debug: 42 rows\n";
    std::cout << "Done\n";
}

#include <iostream>

// Simulates loading data and reports when it has finished.
int main() {
    std::cout << "Loading data\n";
    // std::cout << "Debug: 42 rows\n";
    std::cout << "Done\n";
}

Loading data
Done

Key takeaway#