In C++, Comments are a crucial technique in programming that can help you write more clear and maintainable code. They let you clarify intricate reasoning, jog your memory of crucial information, or clarify a piece of code’s operation to others or even your future self. Comments are a way to add readability to C++ code without compromising program execution.

Types of Comments in C++

There are two primary categories of comments in C++:

1. Single-line Comments
2. Multi-line Comments

Let’s examine them in more detail.

1. Single-line Comments

The // symbol denotes the beginning of a single-line comment in C++; the compiler treats anything on that line that comes after it as a comment.

Syntax:

// This is a single-line comment

Example:

#include <iostream>
using namespace std;

int main() {
    int a = 10;  // Declaring variable a and assigning 10 to it
    cout << a;   // Printing the value of a
    return 0;
}

In the above example, comments are placed to explain the purpose of each line.

When to Use:

• If you would like to add a brief note explaining or clarifying a particular line of code, use single-line comments.

Learn on Youtube:
Comments in C++

2. Multi-line Comments

In C++, multi-line comments are used for explanations that take up several lines or to comment out bigger areas of code. These remarks are enclosed in /* and end in */.

Syntax:

/*
  This is a multi-line comment.
  It can span across multiple lines.
*/

Example:

#include <iostream>
using namespace std;

int main() {
    int a = 10;
    /*
       Declaring variable a and assigning 10 to it.
       Now, printing the value of the variable.
    */
    cout << a;
    return 0;
}

Here, a block of code is commented to describe the purpose of multiple lines.

When to Use:

• When you need to explain a block of code that does a specific task or explain a complex logic, multi-line comments come in handy.

Nested Comments

Multi-line comments /*… */ cannot be nested within other multi-line comments in C++, but single-line comments // can. Nesting is the practice of nested comment types.

Example of Nested Comments:

/*
    This is a multi-line comment.
    // This is a single-line comment within a multi-line comment.
*/

However, the following is not allowed in C++:

/*
    /* This is an invalid nested multi-line comment */
*/

Best Practices for Using Comments

Though helpful, comments should only be used sparingly. The following guidelines should be adhered to when including comments in your C++ code:

1. Keep Your Comments Brief and Clear: Don’t get into detail on how something is done; instead, focus on why it is done. The functionality of the code need to be obvious from the outset.
2. Avoid Over-commenting: Refrain from overcommenting because this can clog the code. Only remark when required. Comments are frequently unnecessary in well-written code with understandable variable and function names.
3. Update Comments with Code Changes: When making changes to the code, it is always advisable to update the comments as well. Future readers may become confused by outdated comments.
4. Use Multi-line Comments for Larger Explanations: Use multi-line comments to clarify the reasoning or the overall structure of the code.
5. Don’t Comment Obvious Code: For example, if something like int a = 10; // Declaring variable an is clear from the code, there’s no need to remark it.

Example: Using Comments in a Real C++ Program

#include <iostream>
using namespace std;

/* 
  This program demonstrates the use of both
  single-line and multi-line comments.
*/

int main() {
    int num1 = 10;  // First number
    int num2 = 20;  // Second number

    // Calculating the sum of two numbers
    int sum = num1 + num2;  

    /*
      Printing the result of the addition.
      The result will be displayed in the console.
    */
    cout << "The sum is: " << sum;

    return 0;  // End of program
}

In this example:

• Single-line comments are used to explain individual lines of code.
• A multi-line comment is used at the top to provide a description of the entire program

Conclusion

Writing code that is clear, legible, and manageable requires the use of comments. Whether you’re working on a big project or a tiny application, using comments well aids in understanding the logic of the code for both you and other users. This may be accomplished in C++ with single- and multi-line comments, which let you efficiently document your code. Recall to be succinct, relevant, and current with your comments!

You may help yourself and others understand and maintain your C++ code more easily by adhering to these recommended practices.

Learn more:
History of C++