C++ Comments

Introduction

Comments are an important part of writing code. They help explain what the code does, making it easier to understand for yourself and others who may read it later. Comments are ignored by the compiler, which means they don’t affect how your program runs. In this chapter, we will learn about the different types of comments in C++ and how to use them effectively.

Types of Comments

C++ supports two types of comments:

  1. Single-line comments
  2. Multi-line comments

Single-line Comments

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

Example

#include <iostream>

int main() {
    // This is a single-line comment
    std::cout << "Hello, World!" << std::endl; // This comment is after a statement
    return 0; // End of main function
}

In the above example:

  • // This is a single-line comment is a comment explaining the code that follows.
  • // This comment is after a statement explains what the previous statement does.
  • // End of main function indicates the end of the main function.

Multi-line Comments

Multi-line comments start with /* and end with */. Everything between these symbols is considered a comment and is ignored by the compiler. Multi-line comments can span multiple lines.

Example

#include <iostream>

int main() {
    /* This is a multi-line comment
       It can span multiple lines
       Useful for longer explanations */
    std::cout << "Hello, World!" << std::endl; /* This comment explains the print statement */
    return 0;
}

In the above example:

  • /* This is a multi-line comment ... */ spans multiple lines and is used for a longer explanation.
  • /* This comment explains the print statement */ explains the statement before it.

Best Practices for Using Comments

  1. Be Clear and Concise: Comments should be easy to understand and to the point. Avoid writing long, unnecessary comments.

    // Good comment
    int age = 25; // Age of the person
    
    // Bad comment
    int age = 25; // This variable stores the age of the person in years
    
  2. Use Comments to Explain Why, Not What: Comments should explain why a piece of code is there, not just what it does. The code itself should be clear enough to explain what it does.

    // Good comment
    int result = calculateSum(a, b); // Calculate the sum of a and b to use later
    
    // Bad comment
    int result = calculateSum(a, b); // Call the calculateSum function
    
  3. Keep Comments Up-to-Date: Ensure that comments are updated if the code changes. Outdated comments can be misleading.

  4. Use Comments to Explain Complex Logic: If a piece of code has complex logic, use comments to explain it.

    // Check if the user input is valid
    // The input should be a positive number and less than 100
    if (userInput > 0 && userInput < 100) {
        std::cout << "Valid input" << std::endl;
    } else {
        std::cout << "Invalid input" << std::endl;
    }
    

When to Use Comments

  • At the beginning of a file: Provide a brief description of what the file does.
  • At the beginning of a function: Explain what the function does, its parameters, and its return value.
  • Within functions: Use comments to explain complex logic, important calculations, or decisions.
  • To-do comments: Indicate future improvements or incomplete sections of code.

Example

#include <iostream>

// This program prints a greeting message to the user
int main() {
    std::cout << "Hello, World!" << std::endl; // Print greeting message
    return 0; // Exit the program
}

/*
 * This function calculates the sum of two numbers.
 * Parameters:
 *  - int a: The first number
 *  - int b: The second number
 * Returns:
 *  - The sum of a and b
 */
int calculateSum(int a, int b) {
    return a + b; // Return the sum of a and b
}

Conclusion

Comments are a crucial part of programming that help make your code more understandable and maintainable. By using single-line and multi-line comments effectively, you can explain the purpose and logic of your code, making it easier for others (and yourself) to understand and maintain. Remember to keep your comments clear, concise, and up-to-date, and use them to explain why your code does what it does, not just what it does. In the next chapter, we will explore variables in C++.

Leave a Comment

Your email address will not be published. Required fields are marked *

Scroll to Top