Comments and Basic Code Formatting

The source code is read by two different entities. The compiler requires the language to be represented correctly. The human reader needs the same code to be immediately understandable weeks or months after it has been written. Comments and consistent formatting are there for the human reader only; the compiler throws them away.

A comment is text that the preprocessor strips away before the compiler ever even gets to see the program. The most commonly used type starts with two bars next to each other and goes to the end of the line.

#include <iostream>

int main()
{
    // This program prints a short greeting
    std::cout << "Hello\n";
    return 0;   // success
}

The text following the // on each of those lines is completely discarded. Only the uncommented statements are compiled, the #include, the main, the message, and the return line. The comments aren’t even put into the running program! They just serve to document what the code around them does for someone reading the program afterwards.

Another style of comment is able to go on for several lines. This style starts with /* and finishes with */.

#include <iostream>

int main()
{
    /* This program prints
       a short greeting
       and then ends. */
    std::cout << "Hello\n";
    return 0;
}

Anything from the opening /* to the closing */ is ignored (including the new lines between them). The compiler only sees the program as it is, and produces the same output of Hello. Multi line comments are there if the note needs to be much longer than a line, but caution should be used.

The characters /* and */ do not nest. If you have a multi line comment nested inside another, the first */ ends the first comment and everything else is treated as source code which always results in a bunch of syntax errors.

#include <iostream>

int main()
{
    /* outer comment
       /* inner comment */
       still inside? */
    std::cout << "Hello\n";
    return 0;
}

The compiler considers the first */ to be ending the comment.

The phrase still inside? */ is then tokenized as normal, which is meaningless and the compiler fails.

Since nesting isn't allowed, multi line comments can't be used safely to comment out multi line comments.

Single line comments are safe to use this way as every // line is its own entity.

Formatting is the second aid to human readers. The compiler disregards virtually all whitespace, so the same statements can be formatted in many different ways. For example, the following two programs are identical from the compiler's point of view:

#include <iostream>
int main(){std::cout<<"Hello\n";return 0;}

#include <iostream>

int main()
{
    std::cout << "Hello\n";
    return 0;
}

Both output an executable that displays Hello, although the second has each of the main components on a separate line, and is indented by a consistent amount in the body of main. Someone reading the code can immediately identify the function's start, what statements it contains, and where it ends. The first version makes the reader work harder to parse a dense stream of characters.

It is normally indented all the statements that live inside of a pair of braces. When it comes to a second level, indent is called one more time.

#include <iostream>

int main()
{
    std::cout << "outer\n";
    {
        std::cout << "inner\n";
    }
    return 0;
}

The statements within the inner block are indented more than the statements that belong only to main. The visual hierarchy corresponds to the logical hierarchy so the program structure is clear without having to count all the braces.

Blank lines are yet another formatting device. They are introduced to separate one set of related statements from another so that each set can be read as a single unit. The compiler considers the blank line to be like any other whitespace and removes it. The blank line only appears in the source for the benefit of the human eye.

Since a compiler never takes comments and formatting into account, they do not affect the execution of a well formed program. They are only useful when a human has to read, debug, or extend the source code. A handful of comments that give an idea of what that part of the program does, by adding indentation and blank lines to the code, will help keep that program readable long after it was written.

#include <iostream>

int main()
{
    /* This program prints
       a short greeting
       and then ends. */
    std::cout << "Hello\n";
    return 0;
}

#include <iostream>

int main()
{
    /* This program prints
       a short greeting
       and then ends. */
    std::cout << "Hello, reader!\n";
    return 0;
}

Hello, reader!