CPP 2 Notes
CPP 2 Notes
2 — Comments
ALEX MAY 1, 2020
A comment is a programmer-readable note that is inserted directly into the source
code of the program. Comments are ignored by the compiler and are for the
programmer’s use only.
In C++ there are two different styles of comments, both of which serve the same
purpose: to help programmers document the code in some way.
Single-line comments
The // symbol begins a C++ single-line comment, which tells the compiler to ignore
everything from the // symbol to the end of the line. For example:
std::cout << "Hello world!"; // Everything from here to the end of the line is
ignored
Typically, the single-line comment is used to make a quick comment about a single
line of code.
The statements above represent one of our first encounters with snippets of code.
Because snippets aren’t full programs, they aren’t able to be compiled by
themselves. Rather, they exist to demonstrate specific concepts in a concise
manner.
If you would like to compile a snippet, you’ll need to turn it into a full program
in order for it to compile. Typically, that program will look something like this:
#include <iostream>
int main()
{
// Replace this line with the snippet of code you'd like to compile
return 0;
}
Multi-line comments
This is one place where using a syntax highlighter can be really useful, as the
different coloring for comment should make clear what’s considered part of the
comment vs not.
Warning
Don’t use multi-line comments inside other multi-line comments. Wrapping single-
line comments inside a multi-line comment is okay.
Typically, comments should be used for three things. First, for a given library,
program, or function, comments are best used to describe what the library, program,
or function, does. These are typically placed at the top of the file or library, or
immediately preceding the function. For example:
// This program calculates the student's final grade based on his test and homework
scores.
// This function uses Newton's method to approximate the root of a given equation.
// The following lines generate a random item based on rarity, level, and a weight
factor.
All of these comments give the reader a good idea of what the library, program, or
function is trying to accomplish without having to look at the actual code. The
user (possibly someone else, or you if you’re trying to reuse code you’ve
previously written) can tell at a glance whether the code is relevant to what he or
she is trying to accomplish. This is particularly important when working as part of
a team, where not everybody will be familiar with all of the code.
Third, at the statement level, comments should be used to describe why the code is
doing something. A bad statement comment explains what the code is doing. If you
ever write code that is so complex that needs a comment to explain what a statement
is doing, you probably need to rewrite your statement, not comment it.
Here are some examples of bad line comments and good statement comments.
Bad comment:
Good comment:
// The player just drank a potion of blindness and can not see anything
sight = 0;
Reason: Now we know why the player’s sight is being set to 0
Bad comment:
Good comment:
Programmers often have to make a tough decision between solving a problem one way,
or solving it another way. Comments are a great way to remind yourself (or tell
somebody else) the reason you made one decision instead of another.
Good comments:
Best practice
Comment your code liberally, and write your comments as if speaking to someone who
has no idea what the code does. Don’t assume you’ll remember why you made specific
choices.
Author’s note
Throughout the rest of this tutorial series, we’ll use comments inside code blocks
to draw your attention to specific things, or help illustrate how things work
(while ensuring the programs still compile). Astute readers will note that by the
above standards, most of these comments are horrible. :) As you read through the
rest of the tutorials, keep in mind that the comments are serving an intentional
educational purpose, not trying to demonstrate what good comments look like.
Converting one or more lines of code into a comment is called commenting out your
code. This provides a convenient way to (temporarily) exclude parts of your code
from being included in your compiled program.
To comment out a single line of code, simply use the // style comment to turn a
line of code into a comment temporarily:
Uncommented out:
std::cout << 1;
Commented out:
// std::cout << 1;
To comment out a block of code, use // on multiple lines of code, or the /* */
style comment to turn the block of code into a comment temporarily.
Uncommented out:
std::cout << 1;
std::cout << 2;
std::cout << 3;
Commented out:
// std::cout << 1;
// std::cout << 2;
// std::cout << 3;
or
/*
std::cout << 1;
std::cout << 2;
std::cout << 3;
*/
There are quite a few reasons you might want to do this:
You’re working on a new piece of code that won’t compile yet, and you need to run
the program. The compiler won’t let you compile the code if there are compiler
errors. Commenting out the code that won’t compile will allow the program to
compile so you can run it. When you’re ready, you can uncomment the code, and
continue working on it.
You’ve written new code that compiles but doesn’t work correctly, and you don’t
have time to fix it until later. Commenting out the broken code will ensure the
broken code doesn’t execute and cause problems until you can fix it.
To find the source of an error. If a program isn’t producing the desired results
(or is crashing), it can sometimes be useful to disable parts of your code to see
if you can isolate what’s causing it to not work correctly. If you comment out one
or more lines of code, and your program starts working as expected (or stops
crashing), odds are whatever you last commented out was part of the problem. You
can then investigate why those lines of code are causing the problem.
You want to replace one piece of code with another piece of code. Instead of just
deleting the original code, you can comment it out and leave it there for reference
until you’re sure your new code works properly. Once you are sure your new code is
working, you can remove the old commented out code. If you can’t get your new code
to work, you can always delete the new code and uncomment the old code to revert to
what you had before.
Commenting out code is a common thing to do while developing, so many IDEs provide
support for commenting out a highlighted section of code. How you access this
functionality varies by IDE.
You can comment or uncomment a selection via Edit menu > Advanced > Comment
Selection (or Uncomment Selection).
You can comment or uncomment a selection via Edit menu > Comment (or Uncomment, or
Toggle comment, or any of the other comment tools).
Tip
If you always use single line comments for your normal comments, then you can
always use multi-line comments to comment out your code without conflict. If you
use multi-line comments to document your code, then commenting-out code using
comments can become more challenging.
If you do need to comment out a code block that contains multi-line comments, you
can also consider using the #if 0 preprocessor directive, which we discuss in
lesson 2.9 -- Introduction to the preprocessor.
Summary