Practical high-ICL techniques

Hacked Code

When you write a hack routine, you should never spec it as is. Specing a hack routine can take forever; it'd be quicker to just finish the routine. It can be helpful to write the spec the way you eventual expect to rewrite the method to be, with a note that the method doesn't work that way yet.

Small Points

Watch for the use of "if" in specs. Often use of this is an indication that the author is thinking in implementation terms. Usually such specs can be rephrased as multiple separate statements. For instance, the postcondition "If x is negative, return -x. Otherwise, return x" is implementationy. Use "Return the absolute value of x" or if a commonly defined term like "absolute value" isn't available, something like "Return v such that v >= 0 and either v = x or v = -x."

Sometimes "if" is used when "if and only if" is meant. Such uses of "if" are perhaps decipherable but aren't quite correct. The math shorthand "iff" to mean "if and only if" is often used in such cases. For instance, instead of "Return true if x > 0", one should write "Return true iff x > 0" or even better, "Return whether x > 0".

Public vs Private Comments

A spec has two faces: one to the caller, the outside; and one to the implementation, the inside. The outside spec is a subset of the inside spec.

When writing the spec one must think about which category each piece belongs in, and put it in the appropriate place. The javadoc program defines which comments become part of the outside spec: /** ... */ type comments on public or protected classes and public or protected entities within those classes. Be sure not to mention private data or methods in such comments, as they must would be referring to something the outside spec reader wouldn't have access to.

Our own code-formatter program is used to generate inside specs. It takes all /** ... */ and /*0 ... */ type comments, whereever they may occur, and formats them as html. The rest of the code (include /*X ... */ comments with X >= 1) is duplicated as is. The result is an htmlified code listing. This is used for inspections or for browsing through the code.


Many common types of code are typically done in ways that are hard to IC. After awhile you'll develop a repertoire of techniques for doing these things in IC-able ways. Here is a list to get you started.
Substantive changes:
    March 25, 1996: created.
Copyright © 1996, Steve Colwell, All Rights Reserved
Home page