How to comment Computer Programs
Code commenting best practices for aspiring computer programmers.
In which we look at 5 kinds of code comments, how they should be laid out,and the general purpose. Language-neutral,and vital for both professional and hobby programmers.
Introduction
The principle behind commenting when writing computer programs is to leave a lasting mark of the intention of the code and any implementation decisions that were made. Computer programming at any level requires that comments are used, if the intention is to ever re-read and/or modify that code again.
There are, however, some compuer programming best practices covering the use of comments. Over commenting, for example, is as bad as under-commenting. Not, perhaps, as bad as not commenting the code at all, but the effort has to be justified by the benefit.
Types of Code Comments
There are 5 principle types of code that can be commented:
- Loops
- Conditions
- User defined Functions & Procedures
- Abstract Data Types
- Open code
In each case, we assume that the code is prefixed by the comment, and that the possibility to place the comment on the same line as the code is not abused. This possibility exists in most languages, except BASIC derivatives that make use of the REM statement.
Commenting Loops & Conditions
A loop should be commented to give the following 3 pieces of information to the reader:
- Approximate number of iterations
- Break / Stop condition
- General purpose
The first of these is important as an indication of how many cycles the loop should go through; it helps understand the purpose, if an extension to the loop is ever considered. The break and stop conditions indicate abnormal (premature) completion (or break), and normal completion (stop). These aid in debugging or code review.
Finally, the general purpose statement may be used to inform the reader of what the loop is aiming to achieve. This may be optional if the purpose is clear from the other two pieces of information - discretion should be used in favor of adhering to the effort/benefit maxim.
Condition statements should be commented with a single line to give a clear, concise, description of what is being tested. Should this not be possible, then it may be more acceptable to break up a compound condition statement (where possible), than cover several lines with a verbose description of the condition itself.
Commenting User Defined Functions & Procedures
It is vital that any user defined functions or procedures be correctly commented, as the reader may have no idea of what the computer program they are reading is trying to achieve. There are 4 basic pieces of information that the comment, precdeing the function/procedure implementation, should contain:
- Statement of purpose
- Non-modified parameters
- Modified parameters
- Return value
The first is fairly obvious, but if it contains more than one distinct operation, perhaps it would be wise to create sub-functions to provide the additional processing. The non-modified parameters are those which are passed into the function/procedure, but which are not altered by it.
By contrast, the modified (or 'through') parameters are those passed in which need to be changed by the function/procedure. Finally, the return value should be listed, along with details of any discrete value lists that might exist for this function; for example, -1 (Error), 0 (No processing), 1 (Success).
Commenting open code and Abstract Data Types
Open code is that which contains staements of assignation or input/ouput. For example, the BASIC PRINT, the standard C printf, or the Modula-2 IO.WrStr would fall into this category, along with any staements assigning a variable to a value. Of course, the variables are named according to conventions outside the scope of this article, but which are covered elsewhere.
Such comments should just give, where necessary, a statement of intention. It is not necessary to comment every single line, so long as other best practices have been followed.
On the other hand, Abstract Data Types have a slightly different set of particular issues associated with them. They may contain data types which are particular to the program in question, or may even be processed in a specific way which is not shared by any other code base.
Subsequently, they need to be commented as much as for use as for clarity. For example, it is not necessary to comment a piece of code which assigns an integer to a value, but is may be necessary to comment an abstract data type assignation of a value where the result is other than expected for the value of that constant data type.
Conclusion
The added benefit of using comments in computer programming is that any documentation that needs to accompany the source code will be easier to write if based on comments. Indeed, some programmers use a kind of meta language that enables the comments to be extracted and used as documenttaion without any additional post-processing.
However, so long as the budding programmer remembers to comment as necessary, they will always be able to pick up a code snippet and modify it or remind themselves of what it does, without having to read every line of code. In a time-constrained world, this might just prove to be the most important reason to comment computer code.
