Comments in C++

Comments in C++ are used to explain and annotate code, making it easier to understand and maintain. They are ignored by the compiler and have no effect on the program’s execution. C++ supports two types of comments: single-line comments and multi-line comments.

Types of Comments

Single-Line Comments

Single-line comments start with two forward slashes (//). Everything following // on that line is treated as a comment and ignored by the compiler.

Example

#include <iostream>

int main() {
    // This is a single-line comment
    std::cout << "Hello, world!" << std::endl; // This comment is ignored
    return 0;
}

Multi-Line Comments

Multi-line comments start with /* and end with */. They can span multiple lines.

Example

#include <iostream>

int main() {
    /*
     * This is a multi-line comment
     * that spans several lines.
     */
    std::cout << "Hello, world!" << std::endl;
    return 0;
}

Best Practices for Using Comments

Commenting Code Purpose and Logic

Use comments to explain the purpose of the code and the logic behind complex algorithms or operations. Avoid stating the obvious, as comments should add value to the understanding of the code.

Example

#include <iostream>

// Function to calculate the factorial of a number
int factorial(int n) {
    // Base case: factorial of 0 or 1 is 1
    if (n == 0 || n == 1) {
        return 1;
    }
    // Recursive case: n * factorial of (n-1)
    return n * factorial(n - 1);
}

int main() {
    int number = 5;
    // Calculate and print the factorial of the number
    std::cout << "Factorial of " << number << " is " << factorial(number) << std::endl;
    return 0;
}

Using Comments for Code Maintenance

Comments can be useful for code maintenance, such as marking sections that need to be reviewed or modified in the future.

Example

#include <iostream>

int main() {
    int a = 10;
    int b = 20;

    // TODO: Optimize the following calculation
    int sum = a + b;

    std::cout << "Sum: " << sum << std::endl;
    return 0;
}

Avoid Over-Commenting

Too many comments can clutter the code and make it hard to read. Focus on commenting the “why” and “what” rather than the “how.”

Example

#include <iostream>

// Avoid unnecessary comments
int main() {
    int x = 10; // Declare an integer variable x and initialize it to 10
    x += 5; // Add 5 to x
    std::cout << x << std::endl; // Print the value of x
    return 0;
}

Using Self-Explanatory Code

Strive to write self-explanatory code where possible. Good naming conventions for variables and functions can reduce the need for comments.

Example

#include <iostream>

// Function to calculate the sum of two integers
int add(int a, int b) {
    return a + b;
}

int main() {
    int number1 = 10;
    int number2 = 20;
    int result = add(number1, number2);
    std::cout << "Sum: " << result << std::endl;
    return 0;
}

Using Doxygen for Documentation

Doxygen is a tool for generating documentation from annotated C++ source code. Special comment formats are used to create structured documentation.

Example

#include <iostream>

/**
 * @brief Function to calculate the factorial of a number.
 *
 * This function uses a recursive algorithm to calculate
 * the factorial of a given non-negative integer.
 *
 * @param n The number to calculate the factorial for.
 * @return The factorial of the number.
 */
int factorial(int n) {
    if (n == 0 || n == 1) {
        return 1;
    }
    return n * factorial(n - 1);
}

int main() {
    int number = 5;
    std::cout << "Factorial of " << number << " is " << factorial(number) << std::endl;
    return 0;
}

Summary

• Single-line comments: Start with // and extend to the end of the line.
• Multi-line comments: Start with /* and end with */, can span multiple lines.
• Best practices: Use comments to explain the purpose and logic of the code, avoid over-commenting, and strive to write self-explanatory code.
• Doxygen: Use Doxygen for generating documentation from C++ code.