Comments in C

The source code of a program is not only read by a compiler, but also by other programmers. For this reason, it is important to document the source code so that it is understandable to everyone.

The C language allows you to insert comments within the source code—sections of text that are ignored by the compiler. Comments are useful for explaining the meaning of lines of code and for adding useful information for the reader.

Documentation and Comments

An important task for a programmer during development is documentation.

It is essential during software development to annotate the most important parts of the code to make it easier to understand for anyone who may read it in the future.

After all, the code in a program is written not only for computers to execute, but also for humans to read. Moreover, multiple people may work on the same project, so the code needs to be understandable by all.

For this reason, C—like other languages—allows you to comment your code. Comments are text segments you can insert into source code that are ignored by the compiler.

In C, comments are written between the symbols /* and */. For example, we can rewrite the hello.c program by adding a comment that explains each line:

#include <stdio.h>

int main() {
    /* Prints the message "Hello, World!" to the screen */
    printf("Hello, World!\n");

    /* Ends the program */
    return 0;
}

The two comments added in the code above do not affect the program's functionality, as they are literally removed during compilation. However, they are useful for anyone reading the code, as they clarify what each line does.

/* This is a comment */

A comment can also span multiple lines using /* to start and */ to end. For instance, we can add a header to our program describing metadata like creation date, purpose, author, and so on:

/*  Program: hello.c
    Author: John Doe
    Date: 01/01/2021
    Purpose: Prints the message "Hello, World!" to the screen */

#include <stdio.h>

int main() {
    /* Prints the message "Hello, World!" */
    printf("Hello, World!\n");

    /* Ends the program */
    return 0;
}

Here, the comment spans multiple lines for readability. This is especially useful when writing longer comments for more complex parts of the code.

One issue with multiline comments is that it's not always clear where they end. It is good practice to place the comment terminator on a separate line like this:

/*  Program: hello.c
    Author: John Doe
    Date: 01/01/2021
    Purpose: Prints the message "Hello, World!" 
*/

This makes it easier to see where the comment starts and ends.

Programmers often get creative, and it's not uncommon to see multiline comments wrapped in a box of asterisks:

/************************************************************
 *  Program: hello.c                                        *
 *  Author:  John Doe                                       *
 *  Date:    01/01/2021                                     *
 *  Purpose: Prints the message "Hello, World!"             *
 ************************************************************/

Again, this is a multiline comment, but styled in a way that makes it stand out.

/* This is a comment
   on multiple lines */

Comment Placement

Previously, we wrote comments on their own lines. However, you can also place comments at the end of a line of code. This is useful for short, line-specific remarks.

For example:

printf("Hello, World!\n"); /* Prints the message */
return 0; /* Ends the program */

printf("Hello, World!\n"); /* Prints the message
return 0; /* Ends the program */

Single-Line Comments in C99

Since the C99 standard, all compilers support a new kind of comment called single-line comment.

This type of comment is designed for short remarks and does not require a closing */.

To write a single-line comment, just use double slashes //. For example:

printf("Hello, World!\n"); // Prints the message
return 0; // Ends the program

The advantage of single-line comments is that they end at the end of the line. You don't need to worry about closing them.

// This is a single-line comment

Disabling Code with Comments

Comments are also useful for another purpose. During development, you can temporarily disable parts of your code by turning them into comments.

This is often referred to as commenting out code.

For example, consider the following program that prints three messages:

#include <stdio.h>

int main() {
    printf("Message 1\n");
    printf("Message 2\n");
    printf("Message 3\n");

    return 0;
}

Suppose we want to disable printing the second message. We can do so by commenting out that line:

#include <stdio.h>

int main() {
    printf("Message 1\n");
    /* printf("Message 2\n"); */
    printf("Message 3\n");

    return 0;
}

In this case, the line printf("Message 2\n"); will be ignored by the compiler and not executed.

In Summary

In this lesson, we studied another important aspect of the C language: comments.

Comments are pieces of text ignored by the compiler and used to document code. They can span one or multiple lines and help explain code behavior.

We saw that comments can be written using /* and */ or, for single-line comments, using double slashes //.

Finally, we learned that comments can be used to temporarily disable code sections during development.