What are C++ Comments?

C++ comments are explanatory text added by programmers in the code to clarify the functionality, purpose, or specific implementation details of the code.The compiler completely ignores comments, which are only meaningful to human readers.

The Two Main Forms of Comments

1. Single-line Comments (//)

Start with double slashes <span>//</span> and end at the end of the line.

// This is a single-line comment
#include <iostream>  // This is an end-of-line comment

int main() {
    // Output greeting to the console
    std::cout << "Hello, World!" << std::endl;  // Output Hello, World!
    
    return 0;  // Program ends normally
}

2. Multi-line Comments (/* … */)

Start with <span>/*</span> and end with <span>*/</span>, can span multiple lines.

/*
 * myfirst.cpp - Display welcome message
 * Author: Programmer
 * Creation Date: January 1, 2024
 * Description: This program demonstrates basic output and comment usage
 */

#include <iostream>

int main() {
    /* 
     * The following three lines output multi-line text
     * Each line uses a separate cout statement
     */
    std::cout << "Come up and C++ me some time." << std::endl;
    std::cout << "You won't regret it!" << std::endl;
    
    return 0;  // Return 0 indicates success
}

Practical Examples of Comments

Example 1: File Header Comment

// =============================================
// File Name: calculator.cpp
// Function: Simple four arithmetic operations calculator
// Author: Zhang San
// Version: 1.0
// Creation Date: 2024-01-01
// =============================================

Example 2: Function Comment

// Function: calculateArea
// Parameter: radius - Radius of the circle
// Return Value: Area of the circle
// Description: Calculate the area of the circle based on the given radius
double calculateArea(double radius) {
    return 3.14159 * radius * radius;  // πr² formula
}

Example 3: Code Logic Explanation

#include <iostream>
using namespace std;

int main() {
    int score;
    
    // Get user input
    cout << "Please enter the exam score: ";
    cin >> score;
    
    // Grade judgment
    if (score >= 90) {
        cout << "Excellent!" << endl;      // 90 and above is excellent
    } else if (score >= 60) {
        cout << "Pass!" << endl;      // 60-89 is pass
    } else {
        cout << "Fail!" << endl;    // Below 60 is fail
    }
    
    return 0;  // Program ends
}

Best Practices for Comments

Good Commenting Habits:

// Good comment example:

// Calculate the year-end bonus for employees
// Rule: Base salary * Performance coefficient + Special contribution award
double calculateBonus(double baseSalary, double performance, double specialBonus) {
    return baseSalary * performance + specialBonus;
}

int x = 10;  // Initialize counter to 10, indicating maximum retry count

Comments to Avoid:

// Bad comment example:

int x = 10;  // Set x to 10 (this is obvious, no need for a comment)

// Addition function
int add(int a, int b) {  // Function name already indicates functionality, comment is redundant
    return a + b;  // Return the result of a+b
}

Special Uses of Comments

1. Temporarily Disable Code for Debugging

#include <iostream>
using namespace std;

int main() {
    cout << "This line of code will execute" << endl;
    
    // Temporarily comment out the following code for debugging
    // cout << "This line of code will not execute temporarily" << endl;
    // cout << "Debug info: x = " << x << endl;
    
    cout << "Continue executing other code" << endl;
    return 0;
}

2. TODO Comments to Mark Work to be Done

// TODO: Add input validation
// TODO: Optimize algorithm performance
// FIXME: There is a boundary case that needs to be handled

int processData(int data) {
    // TODO: Implement complete logic for data processing
    return data * 2;  // Temporary implementation
}

3. Section Comments to Organize Code Structure

#include <iostream>
using namespace std;

int main() {
    // ============ Variable Declaration Section ============
    string name;
    int age;
    double salary;
    
    // ============ User Input Section ============
    cout << "Please enter your name: ";
    cin >> name;
    
    cout << "Please enter your age: ";
    cin >> age;
    
    // ============ Data Processing Section ============
    if (age >= 18) {
        salary = 5000.0;  // Base salary for adults
    } else {
        salary = 3000.0;  // Base salary for minors
    }
    
    // ============ Result Output Section ============
    cout << "Name: " << name << endl;
    cout << "Age: " << age << endl;
    cout << "Estimated Salary: " << salary << endl;
    
    return 0;
}

Compiler Perspective

From the compiler’s perspective, the following code:

// This is a comment
cout << "Hello World";  // Output greeting
/* Multi-line
   comment */

is equivalent to:

cout << "Hello World";

Conclusion

• Single-line Comments: <span>//</span> end at the end of the line
• Multi-line Comments: <span>/*</span> and <span>*/</span> in between
• Compiler Ignores: Comments do not affect program execution
• Important Uses: Code explanation, documentation, debugging, team collaboration
• Good Practices: Write meaningful comments, avoid stating obvious code behavior

Comments are an important tool for writing maintainable and understandable code, and proper comments can greatly enhance the readability and maintainability of the code.