6.5 When Comments are Bad

In the "good old days" of small machine memories and interpreted BASIC, programmers would eliminate the "REM" statements (comments) from their BASIC programs so as to save space and increase execution speed. Whilst this was obviously an appalling programming practice, the small memories and slow microprocessors often made this tempting, if not necessary.

Thankfully, times have changed since then, and most code is now compiled rather than interpreted. However, from time to time one still runs into an environment or situation, or special-purpose language, where comments are either unavailable (no comment feature) or undesirable. Here FunnelWeb can be used to fully document the code without resulting in any comments in the final code at all. For example:

• Comments in frequently used .h header files in C programs can have a significant impact on compilation speed. Often such header files are fairly cryptic and really ought to be well commented, but their authors are reluctant to.
• Comments are undesirable in PostScript header files that must be transferred repeatedly along communications channels (e.g. the Apple Macintosh LaserWriter header file).
• Interpreted programs in embedded systems.
• Hand written machine code in hex dump form could be commented.
• A programmer may wish to annotate a text data file containing lists of numbers that is to be fed into a statistical program that does not provide any comment facility for its input file.

In all these situations, FunnelWeb allows full integrated documentation without any impact on the final code.