comments

C++

“Comment is free but facts are sacred” C P Scott

In C++ programming, the source code of a program can get lengthy like over 100 up to thousands of lines of codes.

So it can be difficult to read a source code (yours or another developer) if the developer who wrote the code wasn’t present to give a general view about the work of the program and explain some part of the source code. Even the developer itself can forget how he/she wrote the code after a while.

This is where we can use comments in the source code.

Basically comments can be helpful in order to open the details of a source code, shape and comb the details if possible and of course as a result gives a chance to other people to speak their mind which help everyone to understand the source-code even better.

In C++ programming we can put comments in places like:

  • Above or below a function.

  • Above or below a variable declaration, initialization and
    assignments.

  • On top or below a preprocessor-directives.

Also we can put comments before or after a data-type name and the variable or function names as well as within the parentheses.

Let’s take a look at an example:

/*
 #include is a preprocessor-directive and is used to replace the file
 named 'iostream' in this example with the actual content of that file.
 */
 #include <iostream>
 
 //This is a prototype of a function and is necessary in order to tell the compiler that there's a function named sum.
 // the body of this function will be somewhere in the source code and it's the job of the compiler to find the body
 // of this function...
 int sum(int firstValue , int secondValue);
 
 // This is the main function and the execution of your program starts from here.
 int main() {
 
 int result = sum(/* the first value is an integer*/3, /* the second value is also an integer*/10);
 // We are calling an object that its class is in the iostream file.
 std::cout<<"resut: "<< result;
 
 // the return type here is an integer and since the value is 0 it means the program terminated successfully.
 return 0;
 }
 
 /* this is the body of the prototype function named 'sum' */
 int sum/* Each variable that we have in the parentheses of a function
 * is called "parameter" */(int /* a comment can be put anywhere and
 * they are ignored by the compilers */firstValue , int secondValue){
 
 return firstValue + secondValue;
 }

If you run the program above, the code will run without any problem even though we have mixed it with comments.

There are two types of comments in C++ programs:

  1. Single line commenting: This type of comment starts with two
    forward-slashes `//` and the comment that comes afterwards.

Note: As the name suggest, this type of commenting is single line and if we need another line for comment, we need to start with two forward slashes // again.

Also in single line comment, we can’t put any actual source code and expect to be compiled by the compiler.

Example:

// this is a single line comment.

  1. Multiple lines commenting: this type of commenting is not limited
    to just one line and we can put comments on multiple lines that follow
    each other.

Here’s the structure of a multiline comment:

/* body of the comment */

Remember: there’s no space between the forward-slash / and the asterisk * that comes before and after the comments.

A multiline comment starts with forward-slash followed by an asterisk followed by the actual comment which can be in one or multiple lines and then followed by another asterisk and ends with another forward-slash.

Note: we can’t use comments between the names of C++ keywords, variables and functions.

Example:

ret/*a comment between the 'return' keyword! */urn 0;

This is illegal and the compiler will return error because the return is a C++ language keyword and we broke it by adding comments in between.