C++ Comments

Types of Comments

// This is a comment

/* This is a
   multi-line comment */

int x = 5; // Store value

// Program: Calculator
// Author: John Doe

🔹 Single-Line Comments

Single-line comments in C++ start with // and are ideal for brief, inline explanations. They help clarify complex logic, describe variable purposes, or temporarily disable code during debugging. For example, // Calculate total price or // User authentication check improves code readability. These comments are ignored by the compiler, so they don’t affect program execution. Proper use of single-line comments enhances maintainability, making it easier for other developers to understand and modify the codebase efficiently.

#include <iostream>
using namespace std;

int main() {
    // This program demonstrates single-line comments
    
    // Declare variables
    int age = 25;
    string name = "Alice";
    
    // Display user information
    cout << "Name: " << name << endl;  // Print the name
    cout << "Age: " << age << endl;    // Print the age
    
    // Calculate age in days (approximate)
    int daysOld = age * 365;
    cout << "Days old: " << daysOld << endl;
    
    return 0;  // End program successfully
}

🔹 Multi-Line Comments

Multi-line comments in C++, enclosed within /* */, provide detailed documentation for code sections, functions, or algorithms. They are perfect for explaining complex logic, summarizing block purposes, or outlining steps in a process. For instance, describing a sorting algorithm or detailing input/output expectations. Unlike single-line comments, they can span multiple lines, offering comprehensive explanations without cluttering the code. This practice improves collaboration and long-term code maintenance, ensuring clarity for future updates or debugging sessions.

/*
 * Program: Simple Calculator
 * Author: Student Name
 * Date: January 2024
 * Purpose: This program performs basic arithmetic
 *          operations like addition and subtraction
 */

#include <iostream>
using namespace std;

int main() {
    /*
       This section declares variables
       for our calculator program
    */
    int num1 = 10;
    int num2 = 5;
    
    /* Perform calculations */
    int sum = num1 + num2;        // Addition
    int difference = num1 - num2; // Subtraction
    
    /*
       Display results to the user
       with clear labels
    */
    cout << "First number: " << num1 << endl;
    cout << "Second number: " << num2 << endl;
    cout << "Sum: " << sum << endl;
    cout << "Difference: " << difference << endl;
    
    return 0;
}

🔹 Good Commenting Practices

Effective commenting involves clarity, relevance, and consistency to enhance code understanding and teamwork. Comments should explain why code exists, not just what it does—for instance, noting business logic behind a calculation. Avoid redundant statements like repeating obvious code actions. Use consistent formatting and update comments with code changes. For example, documenting that a room area calculation (e.g., 12×10 feet = 120 sq ft) meets accessibility standards. Good comments act as a guide, speeding up debugging and onboarding for new developers.

#include <iostream>
using namespace std;

// Function to calculate area of a rectangle
int calculateArea(int length, int width) {
    return length * width;  // Formula: length × width
}

int main() {
    // Get room dimensions
    int roomLength = 12;  // Length in feet
    int roomWidth = 10;   // Width in feet
    
    // Calculate room area
    int area = calculateArea(roomLength, roomWidth);
    
    // Display result with units
    cout << "Room dimensions: " << roomLength << " x " << roomWidth << " feet" << endl;
    cout << "Room area: " << area << " square feet" << endl;
    
    // Check if room is large enough for furniture
    if (area >= 100) {
        cout << "Room is spacious!" << endl;
    } else {
        cout << "Room is cozy." << endl;
    }
    
    return 0;
}

🔹 Commenting for Debugging

Comments are invaluable for debugging by allowing temporary code deactivation without deletion. By commenting out suspicious lines, you can isolate issues and test alternatives, such as disabling a function call to check its impact. For example, if a student score system malfunctions, commenting out grade logic helps verify raw input (e.g., score: 85). This non-destructive approach preserves original code, facilitates incremental testing, and can include notes like // TODO: Fix edge case for tracking unresolved bugs efficiently.

#include <iostream>
using namespace std;

int main() {
    int score = 85;
    
    cout << "Student score: " << score << endl;
    
    // Temporarily disabled - testing different grade ranges
    /*
    if (score >= 90) {
        cout << "Grade: A" << endl;
    } else if (score >= 80) {
        cout << "Grade: B" << endl;
    }
    */
    
    // New grading system being tested
    if (score >= 85) {
        cout << "Grade: Excellent" << endl;
    } else if (score >= 70) {
        cout << "Grade: Good" << endl;
    } else {
        cout << "Grade: Needs Improvement" << endl;
    }
    
    // TODO: Add letter grade conversion later
    // FIXME: Handle negative scores
    
    return 0;
}

🔹 Comment Best Practices

Follow these guidelines for impactful commenting: prioritize clarity, keep comments updated, and integrate them into development workflows. Write in plain language, avoid jargon, and explain complex algorithms or business rules. Use tools like Doxygen for automated documentation and include examples where helpful. Comments should complement clean code, not compensate for poor structure. Regularly review comments during code reviews to ensure accuracy. This disciplined approach reduces technical debt and fosters a collaborative, efficient programming environment.

🔸 Good vs Bad Comments:

// ❌ BAD: States the obvious
int age = 25;  // Set age to 25

// ✅ GOOD: Explains the purpose
int age = 25;  // User's age for eligibility check

// ❌ BAD: Doesn't add value
x++;  // Increment x

// ✅ GOOD: Explains why
x++;  // Move to next array position