Does the name dihydromonoxide sound in any way familiar to you? It should (really, it should). Try googling it (here, I’ll make it easy for you). If and when you do google it, you will be informed by all sorts of sites of the various properties and dangers of this chemical compound. This one, for instance, covers all the dangers of dihydromonoxide (or DHMO) in great and completely accurate detail.

Of course dihydromonoxide and the many warnings against it are all based on a clever use of words. Seen in that light dihydromonoxide is a wonderful example of something I was taught by a professor of mine at university (and reminded of a couple of times today): Shakespeare may have prattled on about roses by any other name, but in reality notation is absolutely everything in our business.

Here’s (another) example of the importance of notation: derivation. Derivation as in calculus, which you were taught in highschool. I’m sure everybody remembers doing endless sums about calculating the derivative function f ‘(x) of a given function f(x), quickly followed by the second derivative f ”(x) and possibly even the third derivative f(3)(x) and fourth derivative f(4)(x). And I’ll bet most of you never even knew (or cared) about the fact that there are a number of different notations in use for a derivative. But there are; and of these, the three most well-known are the Newton notation (which indicated derivation against a function by placing one or more dots above the functor), the Lagrange notation (the notation with the primes used most often for first and second derivative) and the most commonly used of all, the Leibniz notation (which a number in parentheses, an analog to the power-of or exponent notation). Of these, the Leibniz notation is most often used in mathematics. And the reason is simple: once you get beyond second derivatives, the other notations get to be very cumbersome.

Notation is an important factor in our work as computing scientists and software engineers. It often makes the difference between making a piece of software easy to use or cumbersome and unusable. Sometimes it also makes the difference between making a problem easy to solve and difficult. Back in university, for instance, there were a number of courses where we derived solutions to problems from a formal specification. This process involved using predicate calculus, which is very powerful but often cumbersome. However, introducing a useful notation and proving some simple properties of this notation could often greatly reduce the burden of proof in these exercises.

Another example of notation making life easier is a pattern that I’ve employed quite often over the past few years when applying the strategy pattern: in order to select the correct strategy for a specific case, instead of using a gigantic pile of if-statements, I prefer to put instances of all my different strategies in a hashtable using a representative for each case (like a Class instance) as the key. The result looks a little like this:

private Map strategyMap = ...; // Instantiate this somehow 

public void applyStrategyToASpecificCase(final Object theCase) 
{ 
     strategyMap.get(theCase.getClass()).applyTo(theCase); 
} 

One of the reasons I like this, by the way, is that it also mixes well with dependency injection frameworks like Spring.

Like I already said, I was reminded by my professor’s wise lesson a number of times today, both in the positive and in the negative sense. One such reminder occurred when I was working on some UML diagrams using Enterprise Architect (which is a horror I hope you will all be spared). This series of diagrams includes a certain construct which occurs a large number of times in many different places. I quickly found myself wishing there was a simple way to create a shorthand notation for this construct. I was however pleasantly surprised to find that you can embed diagrams in other diagrams (both as embedded images and as symbolic links) and can drill down to them. This allows you to define subactivities for your activity diagrams, for instance. Now if only you could actually include the subactivity within the overall activity as an activity, rather than having to include an activity and put the diagram link next to that (but not connected to the diagram)….

A second example I ran into is related to the definition of a web service interface that is currently being defined. This interface must provide for the inclusion of one or more pieces of configuration data that are retrieved from other XML documents. A very generic solution was chosen by defining a repeatable element called Item, which contains an XMLElement element and a FieldValue element. This solution certainly works, but I think that names like ConfigurationItem, ConfigurationItemName and ConfigurationItemValue are a bit more expressive and therefore make it easier to understand how to use the service.

Notation is one of those subtle little things that I think are too easily overlooked in software engineering, especially given the huge role it can play in making or breaking your system. Notation means the difference between an easily usable API and an airline terminal (ask a travel agent about it, if you’ve never seen one used). It means the difference between self-documenting, maintainable code and unmaintainable code. It can mean the difference between an easily comprehensible and codable solution and a solution that hurts your head just to come up with. It can aid you in achieving separation of concerns (if only by ordering your thoughts). It can even be the key to better-performing code for some problems.

The importance of notation in API design is one of the reasons I am quite enamoured of the notion of a Fluent API, by the way. This interface style promises to make APIs a lot easier to use and a lot less error prone albeit at the cost of requiring more thought on the part of the development team. One of my current projects is experimenting with Fluent APIs right now; I’ll dedicate a future blog to the outcome.

Whether the fluent style will work out or not, I can confirm right now that a clear and expressive interface is always a good idea: two of the projects I am involved with are moving from very generic, “you can put any parameter and value you want in this key-value pair list”-style of interfaces to interfaces that are very explicit about what is needed, what is allowed and what the effect and outcome will be; both projects are reporting far less aggravation in the implementation of their new services than they had previously. Note that the type of data that can be passed through the interface has not changed; just the way the interface forces the client to present this data. Like my professor said, notation is everything.

By the way, in case you were worried: dihydromonoxide (or H2O) is more commonly referred to as water….

Tagged on: