Commenting involves placing Human Readable Descriptions inside of computer programs detailing what the Code is doing. Proper use of commenting can make code maintenance much easier, as well as helping make finding bugs faster. Further, commenting is very important when writing functions that other people will use. Remember, a well-documented code is as important as correctly working code.
If you can’t understand something (or more importantly, don’t think someone else, or yourself months or years later, would understand) without comment, then you should, first of all, try to rewrite it so that you can understand it without the comment. Choose better variable and routine names. Extract some of the code into a new routine.
Note that this does not mean that you should just skip comments entirely; comments should make the source code easier to understand. Comments should be used to add useful information and should be kept in sync with the code.
All programs should be commented in such a manner as to easily describe (in English) the purpose of the code and any algorithms used to accomplish the purpose.
In addition to providing information that increases the comprehensibility of a piece of code, comments should also make the code more readable. The eye should be able to easily follow the flow of the code with the comments.
Whenever possible use the double-slash (‘//’) comment prefix, rather than the slash-asterisk prefix and postfix (‘/* … */’).
Links to external resources are encouraged, but please add context around the link so your fellow users will have some idea what it is and why it’s there. Always quote the most relevant part of an important link, in case the target site is unreachable or goes permanently offline.
Where to Comment
Comments should occur in the following places:
- The top of any program file. This is called the “Header Comment”. It should include all the defining information about who wrote the code, and why, and when, and what it should do. (See Header Comment below)
- Above every function. This is called the function header and provides information about the purpose of this “sub-component” of the program. When and if there is only one function in a file, the function header and file header comments should be merged into a single comment.
- Inline, any “tricky” 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.
Self Documented Code
The self-documented code uses well-chosen variable names (and function names) to make the code read as close to English as possible. This should be your goal.
Variable / Function Comments
In general, the actual name of the variable should be descriptive enough to give a good idea of what the variable is used for. Only in certain cases, comments are required.
For example, naming a variable g has little meaning, but naming a variable gravity gives a much better description of what the variable should contain.
By using proper variable and function names, you should minimize the amount of “external” documentation that is necessary.
File Header Comments
File Header comments are used to identify what is in a file, who wrote it, the date it was written, and a description of what is being solved by the code in the file. All program files should have header comments and it should be located at the TOP of the file!
The file header comment details what is in a file. Among other things it should have:
- The author, date, and course number.
- A description of what the code in the file accomplishes
- A list of any modifications (bug fixes) to the file. Note this is not as important for programs written in class, but important in the real world.
A good file header comment should fully describe the project and purpose of the code in the file. A programmer (or non-programmer for that matter) should be able to read the file header and be able to understand what is the high-level idea and/or purpose behind the code, as well as what data-structures and methods are used.
This can save many hours of time getting a new project member up to speed.
Function Header Comments
Function Header comments are used to describe the purpose of a function. Every function must have a separate header comment. Function headers serve to describe the algorithm which the function implements without forcing the reader to interpret code. Further, it serves to visually separate each function (e.g., in C, multiple functions are written in a single file).
Short and simple functions can have only a few lines of description. As a rule of thumb, the longer the function the longer the header comment.
Remember, always use appropriate amounts of whitespace and good formatting styles. This is as important in coding as in writing technical papers.
By using a function header, you will need to use fewer comments in the actual code segment of the function. This will make your program cleaner and more readable.
Use TODO comments for code that is temporary, a short-term solution, or good-enough but not perfect. A TODO comment provides useful for taking notes about the module you are working on. Make sure you add an author for making it easier for other developers to see that it is you who added the comment.
// TODO: (gunce) is a good example for to do commenting
In general, a comment block of one or more lines that are intended to describe a block of code should indent at the same level as the following line of code. For example:
// The thing is true, and so this code will be executed.
// This is the thing we want to do now.
It is often helpful to provide a pseudo-code comment block at the top of a complex section of code, which describes it. Again, this is helpful only if the comment is maintained with the rest of the code.