Glimmer Labs Presents . . .
The Glimmer Scheme Reference
We tell our students that it is particularly important to clearly
document each procedure they write, preferably prior to writing
the procedure. To help them remember what to document, we have
suggested that they think of the Six Ps: Procedure,
Parameters, Purpose, Produces, Preconditions, and Postconditions.
Since students quickly learn to mimic what faculty do,
in the database of Scheme procedures,
we have tried to use this documentation style for all common
Scheme procedures.
- Procedure
- Names the procedure documented. Important primarily because
it permits the documentation to stand independently from
the code.
- Parameters
- Gives the names, types, and expected roles of the parameters
to the procedure.
- Purpose
- Summarize the purpose of the procedure: What the procedure does.
- Produced
- Name and describe what kind of value, if any, the procedure returns.
- Preconditions
- Formally describe any requirements for the procedure to
function. Typically, the preconditions speak to the parameters,
but they may also speak to the state of the system. We ask
students to indicate whether or not their procedures verify their
preconditions.
- Postconditions
- Formally describe the state of the system and the result of
the procedure. While there is some overlap between
postconditions and the documentation of the produced value, the
documentation of the produced value is usually less formal than
the postconditions.
In writing the preconditions and postconditions, we suggest that students
think about the potential problems that may occur if the procedure is
given inappropriate inputs.
- Problems
- Consider the special cases for the procedure and why they will
succeed or why they might go wrong. Make sure that the preconditions
disallow any of the cases in which the procedure will behave
improperly.
Finally, in the documentation, we've added a few more P's: Package,
Practica, and Pals.
- Package
- A way to group similar procedures together. For example, we group
all the standard Scheme string procedures in the package
"Standard/String".
- Practica
- Examples of the use of the procedure.
- Pals
- A list of other related procedures.