Zen & the Art of C/SIDE Development

In the last part of this series, I wanted to discuss what makes your API easy to call. In earlier posts, we’ve already covered things like naming of parameters and return values, variable scope and Command Query Separation. But there’s more you can do to make things easy for code calling your functions.

Dependency injection

First, let me stress that I’m probably not using this term (from the realm of software testability, AFAIK) correctly. What I mean is this: if a function does its job on an entity defined within that function (e.g. a record variable), that strongly limits what callers can do - they simply have no influence on the function’s subject. If that is the result of a conscious, justifiable, intelligent code design decision - that’s great. If it’s not, it may force your successors to copy your code instead of reusing it.

A typical (and common) example in C/SIDE is a function that performs a certain task on each record in a dataset (a poor man’s Visitor pattern?). If the record variable in question is defined as a local variable within that function (or worse - as a global variable of the object in which the function resides), it won’t be easy to let the function do its job on another dataset (than the one stored in the database table) - the most common example of which being a temporary record variable. A bit like this:

PROCEDURE LessFlexible()
VAR
  MyRecordVariable: Record;
BEGIN
  IF MyRecordVariable.FINDSET THEN
    REPEAT
      DoSomething(MyRecordVariable);
    UNTIL MyRecordVariable.NEXT = 0;
END;

vs.

PROCEDURE MoreFlexible(VAR MyRecordVariable : Record)
BEGIN
  IF MyRecordVariable.FINDSET THEN
    REPEAT
      DoSomething(MyRecordVariable);
    UNTIL MyRecordVariable.NEXT = 0;
END;

I guess it is a trade-off between flexility and effort required to call a function: the LessFlexible variant is easier to call, because the calling code does not require a record variable to pass as a parameter.

Complex parameters vs. simple parameters

Another related dilemma is the following: if my function does its job based on a number of field values in, say, a record variable, do I design the interface so that I need to pass the entire record variable to my function, or in such a way that I pass it only the field values it needs in its current implementation. Something like this:

VAR MyRecordVariable: record;

BEGIN
  […]
  SimpleValues(
    MyRecordVariable.MyFirstField,
    MyRecordVariable.MySecondField,
    MyRecordVariable.MyThirdField);
  […]
END;

PROCEDURE SimpleValues(MyParameter1: decimal, MyParameter2: decimal, MyParameter3: decimal) : decimal
BEGIN
  EXIT(
    MyParameter1 +
    MyParameter2 +
    MyParameter3); // e.g.
END;

vs.

VAR MyRecordVariable: record;

BEGIN
  […]
  EntireRecord(MyRecordVariable);
  […]
END;

PROCEDURE EntireRecord(MyRecordParameter: record)
BEGIN
  EXIT(
    MyRecordParameter.MyFirstField +
    MyRecordParameter.MySecondField +
    MyRecordParameter.MyThirdField); // e.g.
END;

The first option feels nicely decoupled, i.e. function SimpleValues doesn’t care at all where it’s input comes from, as long as it has the right datatypes. Function EntireRecord, however, assumes that its input takes the form of a record variable. If the calling code doesn’t have a record with the desired field values available, it’s going to have to prepare one in order to call EntireRecord.

On the other hand, EntireRecord is less likely to be impacted by changed requirements. If future versions of the algorithm involve field MyFourthField, EntireRecord already has access to the field, without changing the function’s parameter signature. SimpleValues would need an extra parameter, thus breaking any code that depends on it.

How do you normally cope with this devilish dilemma?