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.

Techniques

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.

• Use callbacks to separate interwoven modules. If used often, this might be added to the Java preprocessor as a more convenient feature, since callbacks are currently such a pain to use. Another convenience in the preprocessor might be support for multiple public classes within a single java file.
• Access to subparts for display control by a parent window object, but with regular restricted access for non-display. This enables the global-layout needed for UI design without breaking modularity.
• Use Main's callback queue instead of multithreading.
• Add extra enclosing Panels to Java awt objects like Buttons to fix awt's modularity-breaking "send events to the object's parent" feature.
• Use actual instances instead of one-instance "static" objects. One-instance objects are hard to use correctly because you have to force all callers to coordinate their uses of it.