Commenting involves writing readable descriptions inside of computer programs detailing what the code is doing.
Good commenting makes code much easier to read and understandable and also helps to find bugs faster. All programs should be commented in such a way to easily describe the purpose of the code used to accomplish the purpose.
A third party should be able to understand a program without looking at the code just by reading the comments.
Comments are specially marked lines of text in the program that are not evaluated. They are usually two ways to comment:
The first is called a Single Line Comment and as implied, only applies to a single line in the source code.
Single Line Comment
The second is called a Block Comment and refers to a paragraph of text. A block comment has a start symbol and an end symbol and everything between is ignored by the computer.
Block Comment
Where To Comment:
The top of any program file: It should include all information about who wrote the code, why, when and what it should do or what it does.
Above Every Functions: Provides information about the purpose of the function.
In-line: Any code where it is not immediately obvious what you are trying to accomplish, should have comments right above it or on the same line with it.
How Not To Comment
Comments should be a high level description of what the program is doing. They should not restate something that is obvious.
How To Comment Code:
A single Block comment should be placed at the top of the function and describe the purpose the code used to accomplish the goal.
In-line comments should be used only where the code is not “Self-documenting”. This comment should detail the “idea” behind the code and what is to be accomplished.
Be Aware, TOO MANY in-line comments are as bad as too few.
Self Documenting Code
Self documenting code uses well chosen variable name to make the code readable as possible. This should be your goal.
For example, naming a variable “n” has little meaning, but naming a variable “name” gives a much better description of what the variable should contain.
Best Practices
Use proper variable and function names.
I hope this was understandable enough and able to help out. Thanks for reading.