Effective Use of Comments
Ideally, a program serves two processes: presenting the computer with a set of instructions and secondly providing the programmer with a description of what the program does.
A working program without any comments is a time bomb just waiting to explode. Sooner or later the program will have to be edited or updated and with no comments this job will be much more difficult than it would be with.
Pascal has two flavours of comments. The first starts with { or (* and ends with } or *) respectively. These types of comments are able to span multiple lines as shown below.
(* a single line comment)*
(* A comment
On two lines *)
The other forms of comments begin with // and then go to the end of the line.
// Here is another type of comment which ends at the end of this line.
Some commenting tricks:
(***************************************************************************** ****************************************************************************** ********************** WARNING: This is an example of a ********************** ********************** warning message that grabs the ********************** ********************** attention of the programmer ********************** ****************************************************************************** *****************************************************************************) //-------------------> Another, less important warning <--------------------- //>>>>>>>>>>>>>>>>>>>>>>>>> Major section header <<<<<<<<<<<<<<<<<<<<<<<<<<<<< (***************************************************************************** * We use boxed comments in these examples to denote the * * beginning of a section or program * ******************************************************************************) (* * This is the beginning of a section * * In this paragraph that follows we explain what * the section does and how it works. *) // A simple comment explaining the next line.
Beginning Comment Block
At the beginning of a program it is conventional to have a comment block which stores some or all of the following information:
Heading: The name of the program and a small description of what it does. You could have an incredible unique program but it is useless if no one knows what it does.
Author: Take credit for the program that you’ve made.
Purpose: Why was the program written?
Usage: An explanation on how to run the program.
References: Give credit where credit is due.
File Formats: A list of the files your program reads or writes and a short description of their format.
Restrictions: What are the limits which apply to the program? Should input be formmated correctly as there is no validation?
Revision History: A list of the modifications to the program, who it was done by and briefly what was changed.
Error Handling: If the program finds an error, what does it do with it?
Notes: Any information that hasn’t been covered above.