Comments in C++

In this lesson: Write single-line (//) and multi-line (/* */) comments in C++ with examples and best practices. In Hindi & English.

What is a comment?

A comment is text in your source code that the compiler ignores. It is written for humans — your teacher, your teammates, or you in six months — to explain what the code is for and why it is written that way. Before compilation, the preprocessor strips every comment out, so comments never affect how the program runs.

Single-line comments: //

Everything from // to the end of that line is a comment. It can sit on its own line or after a statement.

#include <iostream>

int main() {
    // Print a welcome message for the class
    std::cout << "Welcome to C++!\n";

    int passMarks = 33;   // CBSE minimum pass percentage
    std::cout << "Pass marks: " << passMarks << "\n";
    return 0;
}

Single-line comments are the most common kind in modern C++ code.

Multi-line (block) comments: /* ... */

Text between /* and */ is a comment, even across many lines. It is handy for a longer explanation at the top of a file or function.

/*
   Program : Student result calculator
   Author  : Aman, Class XII-A
   Purpose : Reads marks of 5 subjects and prints
             total, percentage and grade.
*/
#include <iostream>
int main() {
    int total = 0; /* running total of marks */
    return 0;
}

A block comment can even sit in the middle of a line, e.g. int x = /* default */ 10;, although that style is rarely a good idea.

Block comments do not nest

The first */ always closes the comment. This is a classic mistake:

/*  Old code, disabled for now
    int a = 5;  /* temporary value */
    int b = 7;
*/

The comment ends after temporary value */, so int b = 7; becomes live code and the final */ is a syntax error. To switch off a big block that already contains comments, use the preprocessor:

#if 0
    int a = 5;  /* temporary value */
    int b = 7;
#endif

Documentation comments

Tools such as Doxygen can turn specially formatted comments into HTML documentation. They are ordinary comments that start with /** or /// and use tags like @param and @return.

/**
 * Calculates the percentage of obtained marks.
 * @param obtained marks scored by the student
 * @param maximum  total marks of the exam (must be > 0)
 * @return percentage as an integer from 0 to 100
 */
int percentage(int obtained, int maximum) {
    return obtained * 100 / maximum;
}

Even if you never run Doxygen, this layout makes it obvious how a function should be used.

What makes a good comment?

Other tips:

• Prefer clear names first; add a comment only when the name cannot say it all.
• Keep comments up to date — an outdated comment is worse than none.
• In exams and practical files, a short header comment (program name, purpose) and one comment per logical step is ideal.

Using comments while debugging

"Commenting out" a line is a quick way to test whether it causes a problem:

// std::cout << "debug: total = " << total << "\n";

Remove such lines before you submit or share the code — leftover commented-out code confuses readers.

Common mistakes

• Nesting /* */ comments, as shown above.
• Forgetting to close a block comment — the rest of the file silently becomes a comment and you get confusing "expected ... at end of input" errors.
• Writing / instead of //, which the compiler reads as division.
• Commenting every obvious line, which hides the few comments that matter.
• Leaving old code commented out instead of deleting it.

Summary

• // comments run to the end of the line; /* */ comments can span lines.
• Comments are removed before compilation and do not affect speed.
• Block comments do not nest — use #if 0 ... #endif to disable large blocks.
• /** */ and /// doc comments can be turned into documentation by Doxygen.
• Comment the *why*, keep comments current, and delete dead code.

Related: structure of a C++ program, preprocessor directives, C++ best practices.