next up previous
Next: 1.6.1.3 Examples Up: 1.6.1 The Design Recipe Previous: 1.6.1.1 Data Analysis and

1.6.1.2 Contract, Header, and Purpose

Since Scheme does not accept type declarations for function parameters, a well-written Scheme program must include a comment for each function specifying a type contract for that function coupled with a header declaring the name of the function and its parameters. In contrast, Java requires that the header for a method include type declarations for the parameters and the method result. Hence, every syntactically correct Java program includes type contracts and headers for all methods.

On the other hand, Java does not mandate the inclusion of a purpose statement describing (i) what preconditions (beyond the the types of the arguments) must hold for the method to be called, and (ii) what relationship exists between the inputs and output of a method. The latter is often called a postcondition or output condition for the method. Well-written Java programs include comments providing purpose statements for each program operation other than the trivial methods forming the data definition, e.g. stock constructors and accessors.

For methods defined on composite types (abstract classes at the top of composite class hierarchies), the purpose statement should be attached to the abstract method definition in the top class.


next up previous
Next: 1.6.1.3 Examples Up: 1.6.1 The Design Recipe Previous: 1.6.1.1 Data Analysis and
Corky Cartwright
2001-08-02