Summary: in this tutorial, you will learn how to use C comments to document your code to make the code easier to understand maintain in the future.
Introduction to C comments
A comment is a set of characters that is used to document the code. A C comment starts with a combination of forward slash and asterisk ( /*) and ends with ( */). All comments in program are ignored by the compiler.
The following example demonstrates how to use comments to document your code.
/* This is a comment line that uses to document the code. Comment can span multiple lines. */
A comment can be on the same line with the code as follows. In this case, it is an inline-comment.
int counter; /* for the counter */
Comments are used at the top of the C header ( .h) files and source ( .c) files to describe file’s. It may include the version, author name, date and copyright information. The following comment block can be used at the top of the C header file:
/* File Name : Description : See Also : Author : Copyright : Revision : */
Comments are also used at the top of function to describe what it does, what its parameters are and its returned value. See the following example:
/* Purpose : swaps value of two integers Parameters: *a and *b are integer pointer Return : void See Also : */ void swap(int *a, int *b);
An inline comment that begins with ( //) were add to the C language by C99 standard. Nowadays most compilers support the inline comments. See the following example:
int counter; // for the counter
A complete example of using C comments
The following example demonstrates how to use C comments:
/*
* File Name: main.c
* Author : zentut.com
*
*/
#include <stdio.h>
#include <stdlib.h>
/*
* C comments examples
*/
int main(int argc, char** argv) {
double const PI = 3.14; // PI constant
double radius = 10; // radius of a circle
/* calculate area of a circle */
double area = PI * radius * radius;
/* calculate square of a circle */
double square = 2 * radius * PI;
printf("Area of the circle is %8.2f\n",area);
printf("Square of the circle is %8.2f\n",square);
return 0;
}How to write C comments effectively
Comments play a very important role in your code. Comments are mainly used to document the complex logic of the code to make the code easier to enhance by you and other programmers. Comments may also be used for generating code documentation automatically.
In order to use the comments effectively, you can use the following the tips:
- Comments should describe why a block of code or function does instead of telling how it works. For example, you should comment the code say “calculate area of a circle” instead of “A product of radius and PI”.
- Comments help you and other programmers understand a piece of code easier and faster in the future. Therefore when you write comments, ask yourself if you or other can understand how it works by reading the comments only.
In this tutorial, you have learned how to use C comments to document your code that make it easier to understand and maintain in the future.