HOW AND WHY TO COMMENT IN A C++ PROGRAM

A well-documented code is as important as correctly working code.

The only way to document code is to write comments. Comment is a basically note to yourself that you put into your code. It will remind you in the future that how your code works. Comments are essential in large projects containing hundreds or thousands of lines of source code or in projects which involve many contributors.

Comments are non-executable part of your source code. They are completely ignored by the compiler. They exist just for the benefit of the programmer.

There are many benefits of using comments:

  • Comments help us to understand the code in near future.
  • Comments help us to quickly make changes in the code.
  • Comments can tell other authors that what you have done in your program.
  • Comments can be used to identify errors quickly.
  • Comments make things clear. You give a comment to clarify the intention behind your decision.

There are two types of comment in a C++ program.

  • Single-line comment
  • Multiple-line comment

1: Single-line comment:

A single-line comment is used to write one line description of code. It starts with a double slash // and ends at the end of end of a line. For example:

cout<<”Hello World”; // Prints Hello World

1: Multiple-line comment:

A multiple-line comment is a block of comment. It can go longer than just one line. It starts with /*and ends with */. All the text coming between these two symbols is considered as a comment. For example:

int main()

{ /* This is a

Multiple-line

Comment.*/

cout<<”C++ Programming”;

return 0;

}

Where to comment on C++ program:

You can comment anywhere in your program. But the most important places to write comments are:

  • File Header comment
  • Function Header comment
  • In-line comment

File Header comment:

A file header comment is placed on the top of program file. Basically, it includes:

  • The name of author
  • Contact Information of author
  • Date on which the code was last modified
  • The purpose of program

You may also want to include the brief description of the algorithm and a list of known bugs or suggestions.

A good example of header comment is given below:

/*************************************

* Author: Kamal Choudhary *

* Contact: pakiboy.612@gmail.com *

* Date: Jan 02,2017 *

* Purpose: Program to print a table *

*************************************/

Function Header comment:

A function header comment describes the purpose of a function. You add a comment explaining what the function does.

Same is the case with class. You add a comment at the top of class which explains how class works.

If you write the function header descriptive then you will have to add fewer comments in the actual code segment of function. This will make your program cleaner.

/*************************************

* Function: Even or Odd *

* Description: This function takes an integer *

* And check whether it is even number or odd. *

* Parameters: Integer *

*************************************/

In-line comment:

The comments which are used in general body of the program are called in-line comments. They are usually made using the single line commenting method. They are basically “short notes” about what is going on.

**************************************

* int a=8; // initializes a equals to 8 *

* b=a/2; //Divides by 2 *

* c=a*2; //Multiplies by 2. * **************************************

Tip: Always try to write comments before writing the actual code. In this way, you will write a more descriptive comment.

About Author:

Kamal Choudhary is a tech geek who writes C++ programming tutorials on his blog. He loves to write about computer programming. You canfind his full bio here. Follow He recently published C++ Program to check whether number is even or odd