Comments are a vital part of a program, not for changing how the code is run on a machine, but for maintenance and use by other people. Some people propose that every line that contains code should be commented, others are proponents of fewer comments, but still more lines with comments than lines without. The number and style of comments needed will vary depending on the desires of the person in charge of the project (often times a manager; the boss of the person writing the code) and the complexity of the code. Well written code will require fewer comments as the code is more self explanatory, however a good rule of thumb is that a reader should be able to understand what the code is doing, as well as how it is doing it by reading the comments alone.
5.2.1
Documentation Comments
Documentation comments are blocks of comments whose purpose is to create the documentation for the program. When properly formated programs such as Doxygen will automatically pull these comments out and form them into a nice set of documentation.
Doxygen standards are very similar to Javadoc, both in methods to declare a comment block as documentation and in the tag system used to mark certain pieces of information. Many of the pieces of information important to include in the documentation have keywords called tags that precede the information in the comment block. These tags include brief, return, param and file, and are preceded by either a \or an @ symbol. Either will work, but it is best to choose one of the two and stick with it within any program for consistency’s sake.
There are several variations on how to mark comments as documentation, using both the comment block and comment line styles. The most common method for comment blocks, because it is also the method used by Javadoc, is to begin the comment block with a second asterisk. Often times each line will also begin with an asterisk to improve visibility in the code.
/* * * T h i s is a d o c u m e n t a t i o n c o m m e n t */ /* T h i s is not */
Another method, utilizing comment lines, is to create a block of comments at least two lines long, and beginning with an extra /.
// /
// / T h i s is a d o c u m e n t a t i o n c o m m e n t // /
File Documentation Comments
Each file should begin with a documentation comment block. This block should contain a description of what is included within the file, the date of creation or modification and the authors’ name(s). Often times there will also be a change log or version history included in the file comments as well. A full listing of the usable tags can be found at www.doxygen.com [4]. Here is an example of the file documentation for the source file mainfile.c.
/* * * \ f i l e m a i n f i l e . c * \ a u t h o r P e t e r A l l e y * \ d a t e 7 JUL 2 0 0 9 * \ v e r s i o n 2.3 * * \ S e c t i o n * H e r e we h a v e a d e s c r i p t i o n of the f i l e . As t h i s is * j u s t a d e m o and the f i l e d o e s n't contain anything , * t h i s is j u s t a d u m m y d e s c r i p t i o n .
* \ S e c t i o n
* By the way , t h e r e can be m u l t i p l e s e c t i o n s . */
Macro and Global Variable Comments
Each defined macro and global variable needs to be commented. This will help keep track of which symbols have been used as well has what they have been used for. The tags for these comments tend to be fairly self explanatory, in that the def tag is for defined macros, struct is for structures, typedef is for defined variable types and var is for variable declarations. Again, a full list of these tags can be found at www.doxygen.com [4].
/* *
* \ def A D C _ C H A N N E L * C h a n n e l to use on ADC */
# d e f i n e A D C _ C H A N N E L 1
Function Documentation Comments
Perhaps the most important and most useful documentation comments are those for individual functions. These can appear either with the function prototype in a header file or with the implementation in the source file, or with both; and contain descriptions of the functions as well as what each of the input parameters should be and what the function returns. In a multiple-author file, there may also be an author tag.
These are some of the most common tags for function, and how they are used.
brief: Following this should be a brief, one to two sentence explanation of the function. Should a more in depth explanation be desired or required, put the verbose explanation at the end of the comment block, separated from the tags above it by an empty line.
param: This tag has two arguments separated only by spaces. The first argument is the name of the parameter in question, and the second is a description of what information the function is expecting to be in it. return: This tag indicates a brief explanation of what the return value for
a function is. If the return type for the function is void then there is no need to include this tag.
/* *
* \ b r i e f T h i s is a f u n c t i o n t h a t s u b t r a c t s the f i r s t * a r g u m e n t f r o m the s e c o n d
* \ p a r a m p a r a m 1 The n u m b e r to be s u b t r a c t e d f r o m * \ p a r a m p a r a m 2 The n u m b e r to s u b t r a c t
* \ r e t u r n The r e s u l t of the s u b t r a c t i o n p r o b l e m *
* T h i s is the p l a c e to i n c l u d e a l o n g e r d e s c r i p t i o n of * the f u n c t i o n as n e c e s s a r y , t h o u g h in t h i s c a s e it is * h a r d l y r e q u i r e d due to the s i m p l i c i t y of the f u n c t i o n . */
f l o a t s u b t r a c t ( f l o a t param1 , f l o a t p a r a m 2 ) { r e t u r n param1 - p a r a m 2 ;
}
5.2.2
Non-Documentation Comments
While documentation comments purpose is to explain what the code does, the comments not intended for documentation cover how the code works. These comments are most useful to future programmers attempting to maintain the code. Every comment will give them more information and make their job easier. These are several situations where comments are highly useful.
Lines with complicated logic. Whenever there is a logic check that includes more than one or two operations it is advisable to include a comment specifying, in English, what cases will result in a true result.
Beginnings of conditional blocks. Whenever a section of code may or may not be executed, a comment explaining the block of code and when it will run should be included.
Beginnings of loops. When entering into a loop (while, do-while etc.), it is useful to have a description of what the loop accomplishes, and how long it will loop for. If the loop is set to loop a set number of times, a reason why that number should be included.
Any line with a non-obvious result or reason. If a single line, or even a collection of lines, has a result that is not easily understood, be it the reason, process, or result, a comment explaining the line(s) should be included.
Logically separated blocks of code. Every so often a given task will be completed, and a new task started in the code. Each of these tasks should be commented at the beginning, briefly stating what the section does. This could be something such as “initialization” or “compute motor torque”. When there is a problem discovered in a certain portion of the program, these are the comments that are the first inspected, to find the correct section of code.
These are by no means the only places comments can be. Any time the programmer wants a comment, be it to write down his thought process, get an idea across, demonstrate pseudo-code or even to temporarily remove code from execution, a comment can be included. If in doubt about the usefulness or necessity of a comment, include it: someone, someday, may find it useful.