Wiki Home

Reasonable Pre Condition Principle

Namespace: WIN_COM_API
Preconditions arise from Design By Contract, as suggested by Meyer, Bertrand (1997), Object - Oriented Software Construction, Prentice Hall,

Englewood Cliffs, NJ, ISBN 0136291554. The Reasonable Pre Condition Principle states:

Every routine Pre Condition (in a “demanding” design approach) must satisfy the following requirements:
• The Pre Condition appears in the official documentation distributed to authors of client modules.
• It is possible to justify the need for the precondition in terms of the specification only.

Understanding and applying the Reasonable Precondtion Principle in Visual FoxPro is aided by understanding how the princple is applied in

Eiffel. Each statement of the Reasonable Precondition Principle must be examined individually in the Eiffel context.

• The Pre Condition appears in the official documentation distributed to authors of client modules.

The Eiffel IDE can strip out Class Interface information and place it in a document. The stripped information consists of Method (feature) signatures and contracts (preconditions, post-conditions and class invariants).

Visual FoxPro is not aware of either signatures or Design by Contract. Nor is it natively capable of producing automatic documentation from class code in the same way Eiffel does. Nevertheless, we can coax VFP into providing a tremendous amount of helpful information through Intellisense.

NOTE: Please refer to the Feature Signature article for more information on precisely what a signature is.

By placing the Method signature and contract notes in the PEM Comments, we can get FoxPro's Intellisense to provide us with a wealth of information about how to use Class methods and properties. For instance, we might have the following method signature

on a Class method:

AddGridColumn(toGrd, tcField) --> loCol - Adds a new column for tcField to toGrd and returns loCol as a reference to the added column, 

where tcField is presumed to be a field on the current table in the current work area.

The signature part is the "AddGridColumn(toGrd, tcField) --> loCol" part, while the comments are everything that follows. The signature tells us the name of the method, the arguments passed and what (if anything) the function returns. In this case we pass in a grid object reference and the name of a field (presumably from a table or alias) and we get back a reference (also presumably) to the added column.

From the signature, we know to always send a grid object reference and we know tcField must be a field name. We know a reference to the created column is the guarenteed return. Finally, the comments confirm what we read from the signature, freeing us from "guessing" about how to use the method: AddGridColumn.

The downside to this method is that the comments must be kept in-sync with the actual code. Whereas Eiffel derives the signature from the code itself, we have no such engine available to us in FoxPro, so one method is to make-do with the PEM Comment containing both the method signature and usage (contract) comments.

From the viewpoint of Intellisense-ONLY, we could reduce our PEM Comment to only the "--> Type - Comment" and leave-off the method name and arguments, as they are included already in what Intellisense provides to us. This is a valid viewpoint, but it has two realistic down-sides:

First, we need to see the signature beyond the scope of Intellisense. For instance: We need to see the signature in the Properties form. Thus, we can click the PEM in the Properties form and look below to the comment block and see what the signature of the PEM is. This provides us a "use clue" without having to open the PEM and read the code text. If the PEM comment does NOT contain the arguments, return type and comments (basic contract statements), then we're forced to open the code text and read it to understand or simply to remember over time.

Second, without the full signature and comments for each PEM, we lose the opportunity for automated framework documenation. By having the full signature (PEM Name(args) --> Return - Comments/Contracts), we can now build a tool that strips this information from the VCX, SCX and PRG files and constructs a Class Interfaces Document like is done in other languages (e.g. Eiffel). This is an important point for large and complex frameworks.

See also Design By Contract, Post Condition
Category Class Design
( Topic last updated: 2009.12.29 09:16:14 AM )