Simple, Clean Interfaces

Provide the users of your DataBlade module with a simple, clean interface by following these guidelines where possible:

• Give your routines meaningful, "self-documenting" names.
• Take advantage of polymorphism.
• Limit the number of arguments each routine takes.
• Avoid creating modal routines.

This section discusses each of these guidelines.

Naming Routines

Whenever possible, use generally accepted names for routines using your new data types. For example, the Overlaps() routine in the SimpleMap DataBlade module does precisely what its name indicates. Users know what to expect when they call it.

Because your database server supports polymorphism (see Taking Advantage of Polymorphism), it is possible that another routine of the same name already exists in the system. If you are concerned that your routine provides a different service or has the same signature as another, similarly named routine from another DataBlade module (that is, none of the arguments of your routine are of a data type defined in your DataBlade module), consider renaming the routine or qualifying its name with a three-character DataBlade module prefix such as "USR". Doing so helps avoid conflicts in the system and confusion among your users.

Assume, for example, that you are creating the OtherMap DataBlade module with a routine named Overlaps() that provides a different service than the Overlaps() routine supplied by the SimpleMap DataBlade module. In addition, your Overlaps() routine takes polygon data types not defined in the OtherMap DataBlade module. If the three-character prefix of your DataBlade module is OTH, then you might define your routine as follows:

OthOverlaps(Polygon, Polygon)

However, if your Overlaps() routine takes arguments of data types defined in the OtherMap DataBlade module, you might define Overlaps() as follows:

Overlaps(OthPolygon, OthPolygon)

Taking Advantage of Polymorphism

Your database server supports polymorphism; thus, you can have multiple routines with the same name that take different argument types. For example, a C programmer might be tempted to create distinct names for the following routines that return the larger of their arguments:

bigger_int(integer, integer)

bigger_real(real, real)

However, in SQL it is better to define the routines with the same name, as follows:

bigger(integer, integer)

bigger(real, real)

Limiting the Number of Arguments

To help your users remember how to use your DataBlade module routines, limit the number of arguments they take. Re-evaluate any routines that take more than three arguments; such routines can become unwieldy or can inadvertently become modal (defined in the next section).

Avoiding Modal Routines

When you create DataBlade module routines, avoid including arguments that make them modal; that is, the mode of the routine changes, depending on the third argument. For example, there are a number of different ways to call a routine that computes containment of spatial values. The SimpleMap DataBlade module might implement the following routine:

Containment(polygon, polygon, integer);

This routine determines whether the first polygon contains the second polygon, or whether the second contains the first. The caller supplies an integer argument (for example, 1 or 0) to identify which value to compute; but the purpose of this argument is not immediately evident to a new user of the DataBlade module.

Consider a second design for calculating containment, as follows:

Contains(polygon, polygon) 
ContainedBy(polygon, polygon)

This design is an improvement: not only are the routines nonmodal, but the routine names also clearly explain what computation is performed.