In all programming languages, comments are used to explain something in a normal way, something like post-its you put into lines to remember or to notify other developers. In C and C++, there are two kinds of commenting character series;
1. Single Line Commenting with //
Double forward slashes, // is used as a single-line comment. They are good to add some note before your code lines or after your codes, for example
|
1 2 3 4 5 |
// this is example // this is another example |
You can also put them on the same line of your codes as below,
|
1 2 3 4 |
int i; // in this example i is defined as an integer number float f; // this is another example where f is floating number |
It doesn’t matter where you put but remember that all lines after these // are just reminders. During development sometimes we use them to disable some code lines to see changes or to debug our codes by disabling some of code lines, like this
|
1 2 3 4 |
int i; // float f; |
In this example , float f; line will not be considered during compilation and runtime. For example by doing this you can check if f is used in any lines of all codes, if there is you will get error message because of it is not defined.
2. Multi Line Commenting with /* and */ combo
Multi-line comments are used to add reminders or notes , more than one line. So you dont need to use // for each lines. Any text between /* and */ will be ignored by the compiler: Multi line comments starts with /* and ends with */ as below
|
1 2 3 4 5 6 7 |
/* this is a multi-line comment example that shows how you can use multiline comments in your C++ codes */ |
Professionally when we are coding we use comments in different ways. Some times they are good to give information about your codes at the beginning as below,
|
1 2 3 4 5 6 7 8 9 10 11 12 |
/*--------------------------------------------------------------------------- This software is Copyright (c) 2015 Embarcadero Technologies, Inc. You may only use this software if you are an authorized licensee of an Embarcadero developer tools product. This software is considered a Redistributable as defined under the software license agreement that comes with the Embarcadero Products and is subject to that software license agreement. ---------------------------------------------------------------------------*/ |
Sometimes we use them to disable a function, or disable an old function which has a new one, like this
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
/* float my_function( float a, float b ) { return a+b; } */ float my_function( float a, float b ) { return a*b; } |
In this example we disable the first usage and the second same version is enabled. When you create your own algorithms and you have new ones, you may need to hold the old version. Because sometimes new algorithms or functions are not as good as old ones, so you may need to back to your old algorithm.
Why Comments are Necessary in Development ?
Comments are reminders to yourself to make things easier to understand your code later
As a developer we have many code lines and applications, and as a human it is easy to forget some of parts after days, months may be years. So commenting may help you to understand what is going on there. Sometimes it is really difficult to remember exactly how code lines are running when you back after many days.
We mostly comment on,
- Specific variables represents something important
- for() , do-while(), while() loops.
- Specific classes or functions
- Or any part, any line you think you need to remember later
Comments are reminders to others to let them know and understand your code later
It doesn’t matter if you are a single developer or multi-developer, but if you are developing something new be sure that someone may use it in the future. Otherwise your codes will die with you in a formatted wardrive. This other person may be your team mates, new developers who wants to use your codes, your son, your doughtier, may be your lawyer who can sell rights of it when you die. Comments are a good way to make your codes immoral.
Comments are good to remind some information about your application
Generally codes are in folders with readme notes etc. and they are transferred by compressed packages. Sometimes codes handled alone, so at this point how a new developer will understand your code, your application. What are the copyright of this code ? Who developed ? How long it’s being developed ? How user will compile this ? Any specific options ? Any specific 3rd party libraries, source files, SDKs are needed to compile this code package ? You can easily help about all of these information by using comments.
When Commenting,
Giving some space before commenting would be good to separate codes and comments
Keep your comments readable
Keep your comments understandable ( use simple language)
Keep commenting when coding about your functions, classes, variables etc.
Do not comment everything !
Sometimes using longer definitions for your variables, classes, functions etc. may help you to avoid from more comments as below,
|
1 2 3 4 5 6 7 |
int total_work_days = 650; int number_of_kids = 25; float exhoust_temperature_of_boiler1 = 47.2; |
Design. Code. Compile. Deploy.
Start Free Trial
Free C++Builder Community Edition
