How to Write C++ Comments

Writing good comments is one of the most important skill for software developers.

Great commenting requires you to strike a delicate balance. On the one hand, your comments should allow your code to be interpretable by outside users. On the other hand, too many comments can add bloat to your code and ultimately make it harder to understand.

In this tutorial, you'll learn how you write comments in C++. You'll learn both the technical aspects of including comments in your code as well as professional guidelines on what types of comments you should include (and avoid).

Table of Contents

You can skip to a specific section of this tutorial on how to write C++ comments using the table of contents below:

Types of C++ Comments

There are two main comment types in C++:

  • single-line comments
  • multi-line comments

There is also another kind of single-line comment called an inline comment. We'll explore each of these comment types one-by-one.

1. Single-line Comments

As their name implies, single-line comments are comments that can last up to one line. These types of comments start with a double forward-slash (//) in C++.

Here's an example of a single-line comment in C++:

// this is a single-line comment in C++

Let's consider a more realistic example. Here’s a simple C++ ‘Hello World!’ program that includes single-line comments.

// Cpp single-line comment example
#include <iostream>
int main()
{
 	// Hello World program in cpp  
	cout << "Hello World!" << endl;
	return 0;
}

Here the output of this code:

Hello World!

2. Multi-line Comments

Comments that continue for multiple lines are called multi-line comments.

There are two ways of writing multi-line comments in C++. One way is by starting each line of comment by a double forward-slash (//), which is equivalent to writing one single-line comment immediately after another.

Here is an example of this:

// This is an example of multi-line
// comments using the single-line
// commenting format.

This syntax is the most straightforward method for writing multi-line comments in C++. However, this format can be tedious with very long comments.

For a comment that lasts for a paragraph or more, it's better to use a different syntax. The other method for writing C++ comments involves starting the comment with /* and ending the comment with */.

Here's an example of this syntax in action:

/*
This is how a multi-line comment is made
in C++.  The multi-line comment is wrapped in a pair of
"/*" and "*/" operators. These lines are
ignored by the C++ compiler.
*/

It is possible to nest a single-line comment inside of a multi-line comment. However, this logic doesn't extend to pairs of multi-line comments. You can't nest a multi-line comment inside another multi-line comment.

Here are two examples of how this works in practice:

/* The comment starts here /* and */ this is outside the comment */
// The comment in the first line ends at the first */ and not the second */

3. Inline Comments

As mentioned, in-line comments are an example of single-line comments.

When a line of code is followed by a single-line comment on that same line, we call it an inline comment.

Here's an example to make it clearer:

include <iostream>
int main()
{
	cout << "Welcome to lessons in Cpp." << endl; 	// this is an inline comment
	return 0;
}

Here's the output of this code:

Welcome to lessons in Cpp.

Documentation Comments

Before each file or function begins, a special kind of multi-line comments called block comments are used. These block comments contain information about the file, like it's author and purpose.

Here's how block comments are created:

  • The first line is indented to align the comment with code below the comment.
  • The comment includes details about the purpose of the class or function contained in the file.
  • The comment includes one blank line between the description of the file and a list of tags about the file.

Here's an example of a good block comment in C++:

/*
	CS-11 Asn 2, checks.cpp
	Purpose: Calculate the total of 10 checks
 
	@author Nick McCullum
	@version 2.3 03/05/2020
*/

A properly documented codebase has these types of block comments for all of its files.

Here is another example:

/**
	CS-11 Asn 19
	spherecircle.cpp
	Purpose: Calculates the area of a circle and the volume
	of a sphere.
	@author Nick McCullum
	@version 1.1 5/12/2020
*/
 
#include <iostream>
#include <cmath>
using namespace std;
const double PI = 3.14159;
 
/*
	Returns the area of a circle with the given radius.
	@param radius The radius of the circle.
	@return The area of the circle.
*/
double area(double radius);
/*
	Returns the volume of a sphere with the given radius.
	@param radius The radius of the circle.
	@return The volume of the sphere.
*/
double volume(double radius);
// Controls the program.
int main(void) {
	double radius_of_circlesphere, area_of_circle, volume_of_sphere;
 
	cout << "Enter the radius of a circle\n"
        	<< "and a sphere (in centimetres): ";
	cin >> radius_of_ circlesphere;
 
	area_of_circle = area(radius_of_ circlesphere);
	volume_of_sphere = volume(radius_of_ circlesphere);
 
	cout << "Radius = " << radius_of_ circlesphere << " centimetres\n"
        	<< "Area of circle = " << area_of_circle
        	<< " square inches\n"
        	<< "Volume of sphere = " << volume_of_sphere
        	<< " cubic centimetres\n";
 
	return 0;
}
 
// Returns the area of a circle with the given radius.
double area(double radius) {
	return (PI * pow(radius, 2));
}
// Returns the volume of a sphere with the given radius.
double volume(double radius) {
	return ((4.0 / 3.0) * PI * pow(radius, 3));
}

Why Write Comments in C++?

Comments can often be seen as useless because they don't actually add any functionality to your codebase.

However, it's hard to overstate the importance of good commenting practices.

Now that you've learned the syntax of single and multi-line comments, I wanted to conclude this article by sharing a few reasons why comments are important and some strategies for how to write good C++ comments.

1. Comments Make It Easier To Understand Your Code Later

For a programmer, it becomes really difficult to remember exactly how a program runs when you return to it at a later date. This is especially true when you've worked on other projects in the interim.

Here are a few examples of concepts that good comments can help you recall:

  • What a specific variable represents
  • What a loop is iterating over
  • The role of a specific class or function

Some programmers focus on completing the code first and writing the comments later.

This is a mistake. The single biggest lie in programming is "I'll write the comments later".

The best way to write comments is by doing it as you write the code.

2. Others Can Understand Your Code Without Speaking To You

Production applications can consist of tens of thousands of lines of code. It's nearly impossible for any one developer to build such a large application by themselves.

Because of this, teams of developers work together to build projects. Different developers work on different parts of codebase. They need to refer to each other’s work to piece the project together.

In large projects like this, comments are important for developers to understand code that they didn't write. Using comments, they can skim through the code and understand it's purpose and function. It also helps in a smooth transition if a project has to be handed over to another person completely.

Best Commenting Practices

I wanted to conclude this tutorial by going through some widely-held best practices related to placing useful comments within a codebase.

1. Keep Your Comments Readable

The purpose of comments is simply to explain the purpose of code to programmers and non-programmers alike.

Therefore, it is important that C++ comments are readable. Avoid using jargon in comments and keep the language simple.

2. Whitespace Between Code and Comments is Important

Whitespace makes it easier to recognize comments when you're scrolling through a codebase. This applies to both inline and separate comments:

  • For inline comments, leave two to three blank spaces between the code and comment.
  • For separate comment lines of blocks, leave a single line blank to separate code from comment.

3. Comment as You Write Your Code

As explained earlier, write comments as you write code. Don't postpone adding comments until the code is done, because if you do, the comments will probably never be added.

4. Don't Be "Captain Obvious"

Don't write comments to explain the purpose of very simple code.

Here's an example:

cout<< “Hello World!”;  // Prints Hello World!

In the code above, it is obvious that it prints Hello World! to console. Explaining this in a comment is unecessary and only serves to bloat your codebase.

5. Do Not Use Comments to Explain Problematic Code

Writing comments to explain why a certain piece of code is buggy or dysfunctional is something to avoid at all costs. This is called "smelly commenting". It usually signals that there are likely not so obvious.

No amount of commenting can fix a bug. Instead of writing smelly comments, focus on fixing the problem.

Final Thoughts

A well-documented codebase is one with informative and concise comments.

All languages allow commenting in some form. This tutorial explained how to write comments in C++. I hope you enjoyed it, and that it was useful in your journey as a C++ developer.


Written on June 27th, 2020