Comments in C programming

Comment is non-executable line in source code used to describe a piece of code or program. Comments provides inline documentation of source code and enhances readability of the code. It describes what a piece of code does.

Comments are for readers not for compilers. They make source code more developer friendly.

The compiler has nothing to do with comments, it is non-executable piece of code. Therefore, during the compilation process, pre-processor removes all comments from the source code.

C programming supports two types of commenting style.

1. Single line comments
2. Multi-line comments

Single line comments

Single line comments begin with // double forward slash character. Characters following // is treated as comment and is not executed by the compiler. Single line comments are best suited when you want to add short detail about a complex code that can be described in a line.

Example program to demonstrate single line comments

#include <stdio.h> // Include header file

// Starting point of program
int main()
{
	// Print hello message
	printf("Hello, Codeforwin!");

	return 0;
}

Multi line comments

Single line comment provide support to add short description about the code in one line. However, most often it is required to add long description about working of the code spanning across multiple lines. Definitely in such situation you can add multiple single line comments. But it is recommended to use multi-line comments.

Multi-line comments are used to add a detailed description about the code. It begins with /* character and ends with */. Characters between /* */ are treated as comments.

Multi-line comments can span upto multiple lines. In addition, you can use multi-line comments for both single as well as multiple line commenting.

Example program to demonstrate multi line comments

/**
 * @author	Pankaj Prakash 
 * @description	C program to add two numbers.
 *              Program reads two numbers from user and 
 *              displays the sum of two numbers.
 */

#include <stdio.h>

int main()
{
    /* Variable declarations */
    int num1, num2, sum;

    /* Reads two number from user */
    printf("Enter two number: "); 
    scanf("%d%d", &num1, &num2); 

    /* Calculate the sum */
    sum = num1 + num2;

    /* Finally display sum to user */
    printf("Sum = %d", sum);

    return 0;
}

Advantages of commenting a program

Every developer must have a habit of commenting source code. It is as important as cleaning your bathroom. I already mentioned a well commented program is easy to read and maintain.

Let us consider the following piece of code.

void strcpy(char *src, char * dest)
{
    while(*(src++) = *(dest++));
}

At this point with little knowledge of programming. Do you have any idea what the above piece of code will do? Now consider the same code again.

/**
 * Function to copy one string to another.
 * @src  Pointer to source string
 * @dest Pointer to destination string
 */
void strcpy(char * src, char * dest)
{
    /*
     * Copy one by one characters from src to dest string.
     * The loop terminates after assigning NULL
     * character to src string.
     */
    while(*(src++) = *(dest++));
}

The above commented program gives you a basic idea about the code. Which is where comments are useful. The second program is more cleaner and readable for developers.

Let me add my story to the picture. In my early days of programming. I was a mad over developing small applications. I used to spend all my time on computers. Then, in my fourth semester of graduation I developed a Remote Administration Tool (in C#). Which was pretty cool tool, but lacks comments. After one year when I looked at the code, I got puzzled where to start and where to end due insufficiency of comments. For a moment I thought, did I developed this?

Being a programmer develop a good habit to comment your code. So that not only others but you can also understand your code after ages.