(April 1999)
Why comment? In the lifecycle of a program there will be times when it is necessary to make changes, comments should be viewed as a revision and quality control function. Comments should only be written to aid in the later modification of the program or to find out what version of a particular program or function is currently being used. A good comment states something that is not obvious from looking at the code.
Header comments
Header comments are written because it is sometimes difficult to look into a program and get all the information needed to start working on the code. A header comment should take care of providing the following information to any future developer:
- The title and purpose of the file.
- Authorship and creation date.
- Revision history list.
Example:
;; Title: Garden Path
;; Purpose: To draw a garden path for landscape drawings
;; Written: YZ
;; Creation: 2-5-1998
;; Revisions:
;; 10-9-1999 - Fixed arc bug
;; 15-9-1999 - Saved Osmode and restore at end of program
Indenting level comments
Some comments need to be made in the body of the code, these are known as indenting level comments. As you can tell from the name, the indenting level comments should be at the indenting level of the code they are describing.
Most indenting level comments will be a summary description of a function or module. If you are naming function and variables correctly it should not be necessary to do indenting level comments inside a function. If you feel a comment is required, it should explain the WHYS of the code it is commenting rather than HOW it is doing it. The how should be obvious from reading the code.
If you violate good programming style to make something work, you should add a comment to make sure the next programmer understands why you did it that way. A comment can be just a note to the next guy without really explaining the code itself.
You may want to comment control structures if they get to complicated, but if they are too complicated you may also want to rewrite the structure to make it less complex. The better your structural procedures and naming, the less commenting you will need.
Data structures are also a place where commenting can come in handy to explain how you set up the data and why.
The units of numerical data are a good place to have comments. If your program is expecting the units in feet or millimeters, it should state that somewhere. Ranges of allowable numeric values should also be commented so some checking of the incoming data can be accomplished.
Global data variables should be commented as to what and why they exist. If you have named your global variables correctly the comments may be unnecessary, but you should still look at all global variables and be sure they are clear as to why they are global.
If you are commenting a function make sure you document the inputs and outputs to the function. Also you may want to document any revisions to the function. If the routine is short enough it may not be necessary to comment it. Remember that if a comment is not needed it should not be written. Indenting level comments have only one formatting rule.
- Begin at the current level of indentation and are preceded by two semicolons.
Example:
(defun P-ARRAY ( / n af yn cen c ra )
;; Define number of items in array
(setq n 0)
Summary
Comments should be written as the code is being written. Waiting till the end, when the program is finished is the wrong thing to do. When you are writing the code you will know when a comment is necessary and when it is not. Later you may not be so sure.