In this post, we will discuss soft documentation/comments in programming and why comments are important and where should comments be used.
First of all, we should be aware that comments are the description written in the source code within some special characters so as to get ignored by the compiler while running the code.
In C and C++ programming, we can write a single line comment by using // (double slash) and multi-line comment within /*....*/
Comments are important as much as source code because of the following two reasons.
Reason #1
In an organization, we work in a team; there are many programmers who work on the same project. So, the well commented functions/logics are helpful to other programmers to understand the code better. They can easily understand the logic behind solving any problem.
Reason #2
If you see/edit code later, comments may help you to memorize your logic that you have written while writing that code.
Sometimes, it happens with lazy programmers (who do not comment the code properly) that they forget their implemented logics and waste much more time solving the issue.
So, I would recommend you please comment the code properly so that you or your colleagues can understand the logic better. Writing comments may take time, but it maintains the international coding standards.
Where should comments be placed?
- In the beginning of any source file, you should describe the purpose of writing the source code (functions, logics etc.) with the team members' names.
- Comment function implemented by you with function description, author name, date, lists of parameters, return type, and logic behind solving the problem.
- If you are going to make any changes in a function written earlier, you should describe what changes you are making and why.
I hope this post will help you to become a good programmer because a good programmers always comment his/her code.