07: Comments and Debug Printing

I've shown you a couple of comments in previous code, but didn't really explain it fully. Now we'll explain them better and add one more concept: debug printing. Debug printing is simply using cout to print information about the program while it runs. You could also call it "debug logging" or just "logging."

Comments

A comment is a note you write to yourself or another programmer that explains the code. There's two ways to write a comment in C++:

//

This is a single line comment, place your text after the //.

/* ... */

This is how you write a multi-line comment. You start it with /*, then write as much as you want, even multiple lines, and then end it with */.

When to Use Comments

You'll want to write comments to explain code that might not be clear, or to document code that someone else has to use. When you're just starting out as a programmer you can use comments to help you write code. You can use a process like this:

1. Write out in plain English what you want your code to do.
2. Convert this written explanation into a series of one line comments.
3. Then write your code under the comments to get that comment to work. Run it constantly as you do this.
4. Once it's working, you can clean out the comments or leave them if they help describe the code.

Try this method the next time you have an idea and don't know how to do it. Write in your own words what it should do, convert your words to comments, write the code.

Another time you'll use comments is to quickly comment out code to confirm some idea. Let's say you suspect that a line of code is causing a problem. You just put // in front of it, write an alternative under it and then test if that worked. One warning about commenting out code is if you find you're commenting out more than 1 or 2 lines of code "just in case" then you should just make a backup of your code instead. Too much commented out code is difficult to read.

Debug Printing

Debug printing is a simple concept that weirdly seems to confuse beginners, or they think it's not "real programming." Trust me, printing information about the code is how most programmers debug the code because you usually cannot find bugs by just staring at the code. You need information, and debug printing gets you that information.

What is debug printing? Simply printing a location and some variables. That's it. Not sure why this confuses people, but here's an example:

int main() {
  int param1 = 100;
  cout << ">>> main(): param1=" << param1 << endl;

  cout << "<<< main()"
  return 0;
}

All this does is log the value of param1 every time main() is entered. I use ">>>" to show that I entered the function, then I use "<<<" to show that I've exited main. I might also include the return value.

When to Use Debug Printing

When you can't figure out why you have a bug you should start by logging the variables at key places where you create, change, or use a variable. Later you'll learn about functions similar to main(), and other C++ constructs. For now, when you're stuck, print out variables and information about their locations.

The reason debug printing works so well is the messages you print out are a log of the variable's values over time. You can also use a debugger like gdb and lldb but those are more interactive and work step-by-step, so you lose information about variables as they change. Debugging with printing lets you log out things are changing to find the errors.

The Code

Here is a simple demonstration of using debug printing to log entry to main() and the exit.

View Source file ex07.cpp Only

#include <iostream>

using namespace std;

/*
 * The main function is the entry point
 * for your program. There can be only one.
 */
int main() {
  int test = 1000;

  // I am going to print out some debugging info
  cout << ">>> main(): test=" << test << ", test sizeof=" << sizeof test << endl;

  // now we do a debug print to show exiting main
  cout << "<<< return main(): 0\n";

  return 0;
}

It also shows the two types of comments.

What You Should See

If you run this code you'll see nothing too special. Just those printing output, but more importantly you won't see anything you wrote in comments.

$ builddir/ex07 
>>> main(): test=1000, test sizeof=4
<<< return main(): 0

Break It

There isn't too much to break in this exercise, but once again try to delete random characters to see what errors you get. For example, what happens if you remove the / on each comment?

Further Study

1. Go back to the code from Exercise 06 and annotate each line with a comment explaining what that line does.
2. Try to create a small new program that prints out your own name, age, and height from scratch using comments first. Follow the process I describe where you write the comments for what the code should do, then write the code under it to make that comment work. Do your best to not look at ex06.cpp but if you get stuck take a peek.