In C++, comments are lines of text in the source code that are ignored by the compiler. They are meant to make the code easier to understand by providing explanations, notes, or documentation for developers reading the code.
Comments are crucial for maintaining and debugging code, as they help convey the purpose and functionality of various parts of a program.
Types of Comments in C++
- Single-line Comments: Start with // and extend to the end of the line.
- Multi-line (Block) Comments: Start with /* and end with */, allowing comments to span multiple lines.
Let’s look at examples to see how these types of comments are used in C++.
1. Single-line Comments
Single-line comments start with // and are used to add a short explanation on the same line.
#include <iostream>
using namespace std;
int main() {
int age = 25; // This is a single-line comment explaining the variable 'age'
// Print the value of age
cout << "Age: " << age << endl;
return 0;
}
Explanation:
- // This is a single-line comment… explains the variable age.
- // Print the value of age gives context about the line that follows.
Output:
Age: 25
2. Multi-line (Block) Comments
Multi-line comments start with /* and end with */. They are useful for writing longer comments that span multiple lines.
#include <iostream>
using namespace std;
int main() {
/*
* This program demonstrates how to use multi-line comments in C++.
* It initializes an integer variable and then prints it to the console.
*/
int number = 100; // Initializing the variable 'number'
cout << "Number: " << number << endl;
return 0;
}
Explanation:
- /* … */ contains a detailed description of the program and spans multiple lines.
- Multi-line comments are often used for documenting larger blocks of code or describing the purpose of a program or function.
Output:
Number: 100
3. Using Comments to Disable Code
Comments are often used to temporarily disable or “comment out” code for debugging purposes. This can be done using single-line or multi-line comments.
#include <iostream>
using namespace std;
int main() {
int x = 10;
int y = 20;
// cout << "This line is commented out and won't run." << endl;
/* Uncomment the line below to print the values of x and y
cout << "x: " << x << ", y: " << y << endl;
*/
return 0;
}
Explanation:
- The first cout line is commented out using //, so it won’t be executed.
- The second cout line is commented out using /* … */, so it also won’t be executed.
Output:
- This program produces no output because all cout lines are commented out.
4. Commenting Sections of Code for Documentation
Comments are also useful for adding documentation to sections of code. This is helpful when working with functions or loops, as it explains their purpose to future readers.
#include <iostream>
using namespace std;
/* Function to calculate the sum of two numbers
Parameters:
- int a: The first number
- int b: The second number
Returns:
- int: The sum of the two numbers
*/
int add(int a, int b) {
return a + b; // Returning the sum of a and b
}
int main() {
int result = add(10, 20); // Call the add function with 10 and 20
cout << "Result: " << result << endl; // Display the result
return 0;
}
Explanation:
- A multi-line comment above add describes what the function does, its parameters, and its return type.
- Single-line comments describe the purpose of the add function call and the cout statement.
Output:
Result: 30
5. Adding Notes for Debugging and Maintenance
Comments are often used to leave notes for future developers (or yourself) for debugging or future changes.
#include <iostream>
using namespace std;
int main() {
int counter = 0;
// TODO: Implement user input to initialize 'counter'
for (int i = 0; i < 5; i++) {
counter++; // Increment counter by 1
cout << "Counter: " << counter << endl;
}
// NOTE: Check if 'counter' should reset after the loop
return 0;
}
Explanation:
- // TODO: is a common way to mark tasks that need to be done in the future.
- // NOTE: is a reminder for something that might need attention or modification later.
Output:
Counter: 1 Counter: 2 Counter: 3 Counter: 4 Counter: 5
6. Commenting Code for Complex Algorithms
When implementing complex algorithms, adding comments to explain each step is highly recommended.
#include <iostream>
#include <vector>
using namespace std;
int main() {
vector<int> numbers = {1, 2, 3, 4, 5};
int sum = 0;
// Loop through each element in the vector
for (int i = 0; i < numbers.size(); i++) {
sum += numbers[i]; // Add current element to sum
}
// Calculate the average
float average = static_cast<float>(sum) / numbers.size();
cout << "Sum: " << sum << endl;
cout << "Average: " << average << endl;
return 0;
}
Explanation:
- Each line of the loop is commented to explain the purpose of summing the elements.
- The line for calculating the average is commented as well.
Output:
Sum: 15 Average: 3
7. Commenting Out Code for Alternative Solutions
When exploring different approaches, you can comment out certain parts of the code to try alternative solutions.
#include <iostream>
using namespace std;
int main() {
int x = 5;
int y = 10;
// Method 1: Using addition
// int result = x + y;
// Method 2: Using multiplication
int result = x * y; // Change to multiplication
cout << "Result: " << result << endl;
return 0;
}
Explanation:
- The addition approach is commented out, while the multiplication approach is used.
- This technique is useful for testing different methods without deleting any code.
Output:
Result: 50
8. Inline Documentation in Complex Expressions
Sometimes it’s helpful to add inline comments for complex expressions or multi-step calculations.
#include <iostream>
using namespace std;
int main() {
int a = 5, b = 10, c = 2;
// Calculate the expression: (a + b) * c
int result = (a + b) * c; // Add 'a' and 'b' first, then multiply by 'c'
cout << "Result: " << result << endl;
return 0;
}
Explanation:
- A single-line comment next to result explains the steps of the calculation.
Output:
Result: 30
9. Commenting Multi-line Statements
For readability, you can split long statements across multiple lines and add comments to explain parts of the expression.
#include <iostream>
using namespace std;
int main() {
int a = 5, b = 10, c = 15;
// Calculate complex expression
int result = (a + b) * // Sum 'a' and 'b'
(b - c); // Multiply by the difference of 'b' and 'c'
cout << "Result: " << result << endl;
return 0;
}
Explanation:
- Multi-line comments explain each part of the complex expression, making it easier to understand.
Output:
Result: -75
10. Documenting Classes and Functions
For larger codebases, add documentation above each class and function to explain its purpose, parameters, and return values.
#include <iostream>
using namespace std;
/* Class representing a simple calculator
* Supports basic operations like addition and multiplication.
*/
class Calculator {
public:
/* Function to add two integers
* Params:
* - int a: First integer
* - int b: Second integer
* Returns:
* - int: Sum of a and b
*/
int add(int a, int b) {
return a + b;
}
/* Function to multiply two integers
* Params:
* - int a: First integer
* - int b: Second integer
* Returns:
* - int: Product of a and b
*/
int multiply(int a, int b) {
return a * b;
}
};
int main() {
Calculator calc;
cout << "Addition: " << calc.add(5, 10) << endl;
cout << "Multiplication: "
<< calc.multiply(5, 10) << endl;
return 0;
}
Explanation:
- Multi-line comments provide detailed information about the purpose and usage of each function in the Calculator class.
Output:
Addition: 15 Multiplication: 50
Key Takeaways
- Single-line comments (//) are best for brief notes or inline explanations.
- Multi-line comments (/* … */) are helpful for detailed documentation or disabling multiple lines of code.
- Comments can help explain complex logic, document functions and classes, and leave notes for debugging or future modifications.
- Effective commenting improves code readability, maintainability, and collaboration among developers.