A Word on Comments

A comment in C++ is a way to “hide” the text from the compiler so that it is ignored during program compilation. Comments are simply a way to help other programmers, and even yourself, know what certain sections of code are doing.

While with our early programs the function of our code is usually fairly obvious just by looking at it, with time your programs will become more complex and the function may not be so apparent. You may even forget yourself if you wrote the code a long time ago, so learning to add comments where appropriate is a key programming skill often overlooked by new programmers.

There are two main styles of comments, single-line and block comments.

Single-line comments

By placing two forward slashes // in front of the text you wish to make into a comment, this instructs the compiler to ignore everything starting from the // to the end of the line.

Single-line comment example:

// The line is a comment and is ignored by the compiler.

We can also comment out only part of a line.

In the next example the first part is valid C++ code the compiler will act upon, but once it encounters // it will ignore the rest of the line.

std::cout << "Hello world!" << std::endl;  // From this point to the end of the line is a comment.

Here is another example with multiple lines of code using single-line comments:

for(int i=0;i<10;i++)     // for loop, iterates from 0 to 9
{
  std::cout << "Interrater 'i' is currently: " << i << std::endl;  // Prints the current value of 'i'
}

Comments can also be used above the line they are making a comment about:

// This statement is really long and needs a comment above it
std::cout << "I am a really long string of text to help demonstrate that you should place a comment above me." << std::endl;

If you have many single-line comments in a row used at the end of lines of code, you can use tabs to align them to make it easier to read.

int a,b,c,d,e;                   // Create 5 variables of type int
float f1,f2,f3;                  // Create 3 variables of type float
a=10, b=20, c=30, d=40, e=50;    // Set int values
f1=2.34, f2=1.2, f3=7.85;        // Set float values

 

Comments are also useful to prevent a line of code from compiling and executing. This is useful if you are troubleshooting and just want to temporarily disable a line of code without having to remove it entirely.

int main()
{
    // std::cout << "Hello World!" << std::endl;
    std::cout << "I am alive!" << std::endl;

    return 0;
}

In the above example, only the line that outputs I am alive! will compile and be printed to the console. This is often referred to as “commenting out” a piece of code. It can be useful to see if a certain line of code is causing trouble by temporarily disabling it.

Here is another example, only the line c = a * b; will be compiled and executed. The other lines are “commented out”.

int main()
{
    int a = 5, b = 2, c;

    // c = a + b;
    // c = a - b;
    c = a * b;
    // c = a / b;

    std::cout << "The result is: " << c << std::endl;

    return 0;
}

The output is: The result is: 10  

 

Block comments (multi-line)

 
We can also block out multiple lines of code by using a block (or multi-line) comment. You start a block comment with /* and end it with */.

/*
    I am an example of a block comment.
    I can span multiple lines to help convey a more complete description of complicated code or logic.
    ...
    Use block comments when you have a large amount of text you want to be hidden from the compiler.
*/

 

We can also use a documentation comment block

/**
  * This is a documentation comment block
  * @param xxx does this (this is the documentation keyword)
  * @authr some user (this is the documentation keyword error)
  */

 

 

Code Snippets

 
A fragment of code is often called a snippet. This is usually a small example of code or logic that you intend to share with someone else.

Many of the comment code sections above are example of code snippets. Most are valid C++ code, but they will not run “as is” or on their own.

A example code snippet is:

for(int i=0; i<10;i++)
  std::cout << i << std::endl;

 

By itself the above example will not compile and run as it requires additional functionality.

You need to put code snippets into a functioning program to use them. Oftentimes this can simply be the “Hello Word” framework that CodeBlocks automatically generates when you create a new project.

For example:

#include <iostream>

int main()
{

    std::cout << "Hello World!" "<< std::endl;

    return 0;
}

The above code is the basic framework of a working program CodeBlocks creates by default on startup.

We can simply delete the line: std::cout << "Hello World!" "<< std::endl; and insert a code snippet in its place.

Using our example snippet earlier:

#include <iostream>

int main()
{
  for(int i=0; i<10;i++)
    std::cout << i << std::endl;

    return 0;
}

 

You can now run the snippet in CodeBlocks to see its function.

While this is a simple example this concept will allow you to test and play around with code snippets you may find elsewhere.

Do be aware though, you may need additional code or more likely #include files if the snippet has some dependency from an external library.