Best Practices

You now know both types of comments in C++: // and /* */. But just as important as the syntax is knowing when and how to use comments effectively. Here are the most important rules for good comments.

Rule 1: Explain the WHY, not the WHAT. Good code is often already self-explanatory — what it does is visible from the code itself. A comment is usually only helpful when it explains the reason behind a decision.

// Bad: just repeats the code
// prints Hello
std::cout << "Hello" << std::endl;

// Good: explains the reason
// Greeting shown the first time the app launches
std::cout << "Hello" << std::endl;

The comment "// prints Hello" above std::cout << "Hello" << std::endl; is an example of a good comment.

Rule 2: Keep comments up to date. When the code changes but the comment doesn't, you end up with an outdated comment. An outdated comment is often worse than no comment at all — it misleads others (and yourself).

// Prints the user's first name
std::cout << "Welcome back!" << std::endl;

A comment that no longer matches the current code is called ____.

Rule 3: Don't over-comment. If every single, obvious line gets its own comment, the code becomes more cluttered instead of clearer. Use comments purposefully: to mark sections or to explain truly tricky parts.

// Bad: a comment for every single, obvious line
int main() {
    // prints text
    std::cout << "Hello" << std::endl;
    return 0;
}

// Good: a comment marks only the important section
int main() {
    // --- Greeting ---
    std::cout << "Hello!" << std::endl;
    std::cout << "Glad you're here." << std::endl;
    return 0;
}

When is a comment most useful?