Approxion

Sometimes, when you work with classes or structs, your code is not only dependent on particular fields (attributes, member variables) but on all of them at the same time.

The copy constructor, assignment operator, and the equality operator are prominent examples: if you add a field to your class, these functions need to be maintained in parallel; that is, all of them potentially need to be updated to support this new field. And we all know that it is so easy to forget to update one of them…

I got bitten by this when I used a class that lacked an operator to stream out all of its members. Since I didn’t own the source code of the class (it was part of a library), I couldn’t modify it directly. (I actually could have modified it, but this would have been outright stupid). Instead, I decided to add the missing functionality in my own code. Here is a simplified example:

// Class that I didn't own.
class Fruit {
...
private:
    std::string name;
    int id;
    Color color;
...
};

Here’s what I added in my code:

#include "Fruit.h"

// Stream-out all attributes of Fruit.
ostream& operator<<(ostream& s, const Fruit& fruit) {
    s << fruit.getName() << ":"
      << fruit.getId() << ":"
      << fruit.getColor() << endl;
    return s;
}

It wasn't long until I got a new version of the library in which "Fruit" was extended by another attribute, "weight". Since my code didn't support this new attribute yet, it was broken. Even worse: by (unconsciously) ignoring the new attribute my code failed silently at run-time! Just in case you didn't know: If there is one thing I absolutely can't stand it's if CODE FAILS SILENTLY AT RUN-TIME.

Something had to be done to prevent this from happening again. After a while I came up with the idea of checking the size of class Fruit at compile-time against a hard-coded value. Even though this wasn't perfect (you can easily think of cases where you would get false positives) it gave me a good chance of catching similar modifications next time I rebuilt my own code:

// Stream-out all attributes of Fruit.
ostream& operator<<(ostream& s, const Fruit& fruit) {
    static_assert(sizeof(Fruit) == 24, "Fruit has been tampered with");
    s << fruit.getName() << ":"
      << fruit.getId() << ":"
      << fruit.getColor() << ":"
      << fruit.getWeight() << endl;
    return s;
}

(Note: static assertions are like plain assertions but checked by the compiler at compile-time, not at run-time. I'm using a C++ 2011 feature here, but you can implement static assertions yourself, if your compiler lacks support for them. Read more here.)

Now, if the compiler flagged a failed assertion I would review the public interface of class Fruit and look for any new attributes, update my code along with the reference value of the size and everything would be fine. But how would I get the reference size value (i. e. 24) in the first place?

Calculating the size of a class or struct by hand is not trivial. There can be hundreds of members, including union members, padding bytes, hidden pointers to vtables and the like. A viable solution is to add a temporary print statement that writes sizeof(Fruit) to stdout, but that would require linking and running the program. And what if you are working on an embedded system where there is no stdout or where it is impossible to inspect the value in a debugger?

No, these approaches are too slow and cumbersome. If the compiler knows the size of Fruit it should be able to tell me. But how?

This question haunted me for quite some time. I devised a cunning plan: why not add a statement containing a syntax error that somehow forced the compiler to spit out the size of my class. Among other things, I tried this:

extern int foo[-(int)sizeof(Fruit)];

This hack exploits the fact that in C/C++ it is illegal to declare an array of negative size. I had hoped to get a message like this:

FruitApp.cpp:39 error: size of array ‘foo[-24]’ is negative.

Alas, all compilers that I checked-out just gave a worthless error message among these lines:

FruitApp.cpp:39 error: size of array ‘foo’ is negative.

There was no clue as to what the actual size was. Too bad. The compiler knows the answer but it doesn't want to tell me!

I was just about to give up when I suddenly had another idea: what the compiler would always tell me is the line on which an error occurred. Why not attempt to create many arrays, where the size is decremented, starting from sizeof(Fruit):

extern int foo_1[(int)sizeof(Fruit) - 1 - 1]; // Fails if sizeof(Fruit) == 1
extern int foo_2[(int)sizeof(Fruit) - 1 - 2]; // Fails if sizeof(Fruit) == 2
...
extern int foo_42[(int)sizeof(Fruit) - 1 - 42]; // Fails if sizeof(Fruit) == 42
...

I would just include this header file and the compiler would compile line after line until it hits a syntax error due to a negative array size. When it does, it would report the corresponding line number which in turn corresponds to the size of Fruit. G-r-e-a-t!

Generating this include file (getsize.h) was straightforward: I cobbled together a simple Bash for-loop:

for ((x=1; x<=65535; ++x)); do
    echo "extern int size_is_$x[(int)sizeof(GETSIZE_TYPE)-1-$x];";
done > getsize.h

I used it like this:

ostream& operator<<(ostream& s, const Fruit& fruit) {
    #define GETSIZE_TYPE Fruit
    #include "getsize.h"
    static_assert(sizeof(Fruit) == 16, "Fruit has been tampered with");
    s << fruit.getName() << ":"
      << fruit.getId() << ":"
      << fruit.getColor() << ":"
      << fruit.getWeight() << endl;
    return s;
}

Compiling this code yields the following error messages (the exact messages may vary, depending on the compiler that you use):

getsize.h:24 error: size of array ‘size_is_24’ is negative
getsize.h:25 error: size of array ‘size_is_25’ is negative
getsize.h:26 error: size of array ‘size_is_26’ is negative
getsize.h:27 error: size of array ‘size_is_27’ is negative
...

The first line that is reported as erroneous is the size of class Fruit, 24 in our example. Once you know the size you just need to update the reference value and comment out the two lines to have them ready when you need them again.

ostream& operator<<(ostream& s, const Fruit& fruit) {
    // #define GETSIZE_TYPE Fruit
    // #include "getsize.h"
    static_assert(sizeof(Fruit) == 24, "Fruit has been tampered with");
    s << fruit.getName() << ":"
      << fruit.getId() << ":"
      << fruit.getColor() << ":"
      << fruit.getWeight() << endl;
    return s;
}

You might find all of this a bit hacky, but I happen to like it very much. It serves a good purpose and nicely solved my problem. On top of that, it gave me a really good time. What more can one expect?

Designing intuitive interfaces that are easy to use and easy to learn is hard, often very hard; and for economic reasons it might not always be possible to strive for perfection. Nevertheless, in my view, at the very least, interfaces should be designed such that obvious, day-to-day usage doesn’t lead to damage.

In his classic book “Writing Solid Code”, Steve Maguire calls confusing interfaces that lead to unexpected bugs “Candy Machine Interfaces”. He tells a story from a vending machine at Microsoft that used to cause him grief: The machine displayed “45 cent” for “number 21″, but after he had finally inserted the last coin he would sometimes enter “45″ instead of “21″ (and would get a jalapeño flavored bubble-gum instead of the peanut butter cookie that he wanted so much — Ha Ha Ha!). He suggests an easy fix: replace the numeric keypad with a letter keypad and no confusion between money and items would be possible anymore.

The other day I did something like this:

rsync -r /media/backup/gamma/ /home/ralf

My goal was to recursively copy the ‘gamma’ folder to my home folder. What I expected was a ‘gamma’ folder within my home directory, but instead I ended up with hundreds of files from the ‘gamma’ directory right at the top-level of my home directory — the ‘gamma’ directory simply wasn’t created!

I have to confess that similar things sometimes happen to me with other recursive-copy-like tools, too — this seems to be my candy machine problem. Now you know it.

As for ‘rsync’, there is a feature that allows you to copy just the contents of a directory, without creating the directory, flat into a target directory. Granted, this is sometimes useful, but do you know how to activate this mode? By appending a trailing slash to the source directory! That’s what happened in my case. But I didn’t even add the slash myself: if you use Bash’s TAB completion (like I did) a trailing slash is automatically appended for directories…

But good old ‘cp’ puzzles me even more. If you use it like this

cp -r /from1/from2/from3 /to1/to2

it will copy ‘from3′ to a folder named ‘to2′ under ‘to1′ such that both directories (‘from3′ and ‘to2′) will have the same contents, which is more or less a copy-and-rename-at-the-same-time operation. Unless ‘to2′ already exists, in which case ‘from3′ will be copied in ‘to2′ resulting in ‘to1/to2/from3′. Unless, as an exception within an exception, there is already a ‘from3′ directory under ‘to2′; in this case ‘cp’ will copy ‘from3′ flat into the existing ‘to2/from3′ which might overwrite existing files in that folder.

Both, ‘cp’ and ‘rsync’ suffer from fancy interfaces that try to add smart features — which is normally good — but they do it in an implicit, hard-to-guess, hard-to-remember way — which is always bad. Flat copies are sometimes useful but they might be dangerous as they could inadvertently overwrite existing files or at least deluge a target directory. A potential cure could be an explicit ‘–flat’ command-line option.

To me, a wonderfully simple approach is the one taken by Subversion: checkouts are always flat and I’ve never had any problems with it:

svn checkout http://someurl.com/marble/trunk ~/work/marble

This copies (actually checks-out) the contents of the ‘trunk’ flat into the specified destination directory — always, without any exceptions. That’s the only thing you have to learn and remember. There are no trailing backslashes or any other implicit rules. It will also create the target parent directories up to any level, if needed.

Naturally, dangerously confusing interfaces exist in programming interfaces, too. Sometimes the behavior of a method depends on some global state, sometimes it is easy to confuse parameters. The ‘memset’ function from the C standard library is a classic example:

memset(buffer, 32, 40);

Does this put 40 times the value of 32 in ‘buffer’ or is it the other way around?

I have no idea how many programmers don’t know the answer to this question or how many bugs can be attributed to this bad interface, but I suspect that in both cases the answer must be “way too many”. I don’t want to guess or look up the specification in a manual — I want the compiler to tell me if I’m wrong. Here is an alternative implementation:

typedef struct {
    char fill;
} memset_fill_t;

void memset(void* p, memset_fill_t fill, size_t n);

Now you can either write

memset_fill_t fill = { 32 };
memset(buffer, fill, 40);

Or, if you want to save a few characters

memset(buffer, (memset_fill_t)32, 40);

In either case, if you confuse the fill character with the length parameter the compiler will bark at you — a parameter mix-up is impossible.

Like I said in the beginning: designing intuitive interfaces is hard but spending extra effort to avoid errors for the most typical cases is usually a worthwhile investment: don’t make people think, make it difficult for them to do wrong things — even if it sometimes means a little bit more typing.

It is common wisdom that opposites attract. In programming, however, it is desirable to keep things that are related together — that’s at least what the “Principle of Proximity” states.

This principle has many manifestations, some of which are well known by most software developers, for instance:

-Keep the documentation (comments) as close as possible to the code;
-Initialize variables as close as possible to the point where you use them;
-Limit the scope of declarations (i. e. use namespaces and don’t make constants public if private is sufficient);

As opposed to opposites, related things not always attract, or — as a matter of fact — attract in a suboptimal way.

Here is an example. Assume that you have to process a list of different objects (let’s call them “boxes”, for the sake of this example) that you have just received, maybe over a socket connection. This list always consists of a blue box, a red box, and a green box, exactly in that order. These boxes are encrypted and protected by an integrity checksum. Before actually processing them, you need to perform decryption and integrity checking. (Also assume that the boxes are completely different. They have different content, different security mechanisms, and require different processing.) Below is one way to go about it:

void onReceiveBoxes1(void* boxes) throw(BoxSecurityException) {
    // Get pointers to boxes.
    blueBox_t* blueBox = (blueBox_t*)boxes;
    redBox_t* redBox = (redBox_t*)(blueBox + 1);
    greenBox_t* greenBox = (greenBox_t*)(redBox + 1);

    // Check box integrity and decrypt box content.
    applySecurityToBlueBox(blueBox);
    applySecurityToRedBox(redBox);
    applySecurityToGreenBox(greenBox);

    // Process the actual boxes.
    processBlueBox(blueBox);
    processRedBox(redBox);
    processGreenBox(greenBox);
}

At first glance, this code doesn’t look bad at all. It is grouped in such a way that the three steps are clearly visible: 1. get a box; 2. apply security to box; 3. process box. If you zoom out a little, the structure looks like this:

    operation 1
        object a
        object b
        object c
    operation 2
        object a
        object b
        object c
    operation 3
        object a
        object b
        object c

Is this the principle of proximity in action? Are related things close together?

Not really. The things that are close together are the objects under each operation, but the objects themselves have little in common. Contrast this with this approach:

void onReceiveBoxes2(void* boxes) throw(BoxSecurityException) {
    // Handle blue box.
    blueBox_t* blueBox = (blueBox_t*)boxes;
    applySecurityToBlueBox(blueBox);
    processBlueBox(blueBox);

    // Handle red box.
    redBox_t* redBox = (redBox_t*)(blueBox + 1);
    applySecurityToRedBox(redBox);
    processRedBox(redBox);

    // Handle green box.
    greenBox_t* greenBox = (greenBox_t*)(redBox + 1);
    applySecurityToGreenBox(greenBox);
    processGreenBox(greenBox);
}

The structure is now inverted:

    object a
        operation 1
        operation 2
        operation 3
    object b
        operation 1
        operation 2
        operation 3
    object c
        operation 1
        operation 2
        operation 3

The objects and their operations are close together; in fact, they are completely encapsulated. I like to call this ‘encapsulation at runtime’, which is not to be confused with traditional object-oriented encapsulation where you put data and its related operations close together at coding time, in a class. (Which is another instance of the principle of proximity, BTW.)

What I don’t like about onReceiveBoxes1 is that it mixes up things that are unrelated: order of boxes and order of box actions. Just because the boxes are ordered in a particular way, doesn’t mean that we have to perform the box actions in that particular box-order. Unnecessary dependencies are usually bad for maintenance.

Ah, maintainability, that’s where the second implementation really shines! If you have to add a yellow box someday, you just copy and paste the block of an existing box and do some minor modifications. And if the order in which boxes arrive changes, adapting onReceiveBoxes2 is likewise trivial. Better maintainability means that the risk of introducing an error is much lower, which in turn means that you spend less time debugging and have more time for doing code katas.

Honoring the principle of proximity almost always gives you better efficiency, either. Notice that in the first implementation, the pointers to all boxes have a fairly long lifetime and must be kept in memory (or CPU registers) as they are needed until operation 3 has finished. onReceiveBoxes2 only needs a pointer to the box that is currently worked on, which means that the compiler only needs to allocate one pointer.