Almost a year ago Charles Calvert and Robert Kozak wrote an excellent article about commenting techniques: "I have a comment...". We see so many poorly commented programs that I think this topic is important enough to address again - slightly differently. Most code in CodeCentral and even the VCL source modules distributed with Borland Delphi 5 are not commented properly.
It depends on who reads the code, and what is the intention of the code.
We write these for testing a new feature of the new version of the programming language tool, or calculating something quickly. These programs are usually deleted after we learned using the new feature or got the result of the calculation. But even if we save them it is unlikely that we need them again.
Programs of this kind are not commented. Sometimes they live longer than we expect, and we find them years after they are written in old backup CDs and wonder who wrote them so poorly, why are they written, and what on earth they might be doing.
These programs help us learning more complex things in, like the database handling or graphics in Delphi. Such programs may perform complex operations, even if the user interface is somewhat sketchy. Help file and additional documentation is rarely made, and we must rely entirely on the comments.
Programs that we write in our free time for just the pleasure of creating are another group of these programs. We often forget to comment these, thinking that no one will see or use them.
Why shall these programs be commented at all? No one will see them.
Because they live long, and writing comments helps us understand the working
of the programming language. When we buy the next version of the programming
language tool these commented programs will help us learning the new features.
These are the typical commercial programs, and found everywhere. We can rely on the skills of the team, follow common coding techniques, and comment only those things that are uncommon. Additional documentation and help file usually exist, thought they cover mostly the using of the program and does not help much in the maintenance.
It often pays off to keep a private help file, and place most of the explanation there. The code will be more readable despite the reduced amount of comments, and the explanations are readily available via context sensitive help.
A typical example is the help file for a new component. A reusable component with context sensitive help file is a valuable asset that will help generating new project quickly, and help in maintaining an existing one.
If we plan to publish the source either as a freeware, or a shareware or part of a commercial package we must think that users of the program will read it and form their opinion about our programming skills based on it. Every program of this kind is a sort of reference work. We can assume that users who are interested in the code are good programmers, and know how to find information in help files and additional documentation so we do not have to rely entirely on comments. However we have to make allowances for programmers with different level of knowledge and background and explain everything in details. Help files are very good to explain the general structure and the intent of the code, while comments can explain the finer details.
There is another advantage of commenting the program well: if users understand the way program works they might be able to help in improving it and finding bugs.
These are the most critical programs of all, because they will be read by people who do not understand every aspects of programming, and may not be able to use the information provided separately. Here we have to explain how the program works and not only the why, and repeat with other words what is in the help file. We have to be very careful balancing the information we give in comments and in separate printed or electronic documentation and in help files. If we rely to much on information provided elsewhere, the code will be difficult to read. On the other hand if we write everything in the comment it will hide the code, and give the impression that these programs are so complicated that without a lot of comments they are useless.
We cannot always avoid using tricky code. In time critical parts of the program we have to restore to machine dependent tricks and even to the use of assembler instructions. Usually only a tiny portion of the code is time critical. Commenting every line in these parts is not really a burden.
If it is possible to rewrite the code in a less tricky manner, it may be considered to conditionally include that part too. An example is the conversion of a 32 element long Pascal style set to a packed binary C record. Internally both are stored as 32-bit integers, each bit corresponding to one element. The standard conversion uses the in operator to test every bit in the Pascal set and sets or resets the bits in the C record one by one. It is 64 assembly instructions long, it does not make any assumption on the way of storage and easily understandable even without comments. The tricky way is only two assembly instructions long, moving one doubleword to the other.
Markers are used as temporary notes to yourself or other programmers on your team marking debug lines or unfinished code fragments. When the project is completed these marks, and often the code they refer to, are deleted.
In the early days of programming files were short, compiled separately and linked. A good rule of a thumb was to keep the file length under 100 lines. Memory was small, editors were cumbersome.
With the emerging of object oriented programming, and the growing size of projects these rules are no longer apply. Editors can handle any length of file, compiling is under seconds, but the programs are much bigger. Ten years ago a million-line program was unthinkable, nowadays even editors can grow that big. Windows.pas is only a header file but 3124 lines long and is not overloaded with comments.
Usually a group of similar components and subroutines are kept in one file. The file length is a several thousand lines long. To manage files that big they are separated into sections by separator comment lines. For example the interface is the first section, global object definition is the next, all the subroutines of one object are in the following sections, and the initialization/finalization code is the last section. Different separators patterns can be used for even finer resolution.
Typical separator lines are identical long comment lines full of -, =, #, *, \ or other symbols.
This type of comment summarizes how the code works. It allow someone not familiar or interested in the details to scan through quickly. The comment is usually placed before a block of instructions, or before a local subroutine. As programs grow in length this comment became more and more important.
Description tells us how to use a subroutine or a component. The comment is usually placed before subroutines, before objects, and at the beginning of the file or section. A well written description of a subroutine does not bother us by telling how the subroutine works, only lists the input and output parameters, give short description of the function, and possible side effects. A more detailed explanation can be given in a help file, as it often happens in the case of components, global objects and global subroutines.
While writing the program!!! It is wrong to wait until the completion of the code. Comments can help while writing the program, and you may forget to write them in the end, or forget how some tricky parts worked. It is acceptable to write summary information and copyright messages finally, but it is not a good practice. (You know who is the copyright holder right from the beginning - Why not start the file with it?)
The main rule is to write comment in a way that does not interfere with the reading and maintenance of the code. Writting separate comment lines before each line is unnecessary, and makes the the program flow more difficult to follow. The best place for comments are at the beginning of the subruotine or block of code or object definition. If you keep subroutine shorts, there is little need for anything else.
Endline comments is also useful to explain the intent of the code. I start endline comments at position 81. This allows me to read the code and the comment separately, or read the code only and refer to the comment only for clarification. Using XGA resolution and 8 point size letters about 120 characters/line is managable and printable. 80 position is almost always enough for the code, and the 40 characters length is not too great restriction on endline comments. I prefer to have longer lines to using abbreviations.
Endline comment shall give information that is not obvious from the code. If you have nothing to add then do not comment rather than repeating the code.
Multi-glyph controls components are my freeware components that I have written for publication with the intention that it might be useful for learning advanced programming skills. There are plenty of comments in the source explaining everything not obvious, but most of the information for component users is provided in the help file. The readme file gives detailed installation instructions, and contains the usual copyright and licensing information.
I included the source of the help file to encourage programmers to create their own help file, and tried to make it appear almost identical to Delphi 5 help pages.
Two HTML pages are based on this component package. One describes the component, the other gives information about generating help files that integrates seamlessly into the Delphi Open Help system. The first is mostly repeated in the enclosed readme file and help file, while the second is maintained separately and reference the component only as an example of creating help files.
Written by Pintér Gábor
Székesfehérvár, Kriványi u. 15.
H-8000, HUNGARY
Tel: +36 30 3489752, Fax: +36 22 304326
Email: propix@propix.hu
Web: http://www.propix.hu