Talking with a Lisp

Feynman has often been described as a raconteur and I am sure he deserves that epithet without me justifying it or otherwise. The reason he was called so was because of his extremely direct manner of explaining, in the simplest of terms, some of the most complex concepts of advanced physics. His video lecture series was one of those myriad events which further reinforced his stature as a clear-headed genius. Now, that is not as trivial as it may seem at first. In my opinion, and arguably in an objective sense as well, the true measure of genuine understanding of any subject is the ability to express it without equivocation or self-doubt. No doubt eloquence, directness of approach and pithiness are characteristics which are often innate (and cultivable to a great extent through practice) but these attributes notwithstanding, the skill to present the matter at hand in a fluid and intelligible manner – caressing the topic with the confidence and prowess of a professional and actually putting forth all the salient points without diluting the content, is true raconteurism. Feynman was adept at that but recently I discovered another genius who actually surpasses him in this regard. Come forth, Joshua Bloch!

To the true technologist, Joshua Bloch requires no further introduction. He is the master and creator of the Java Collections framework (which is one of the finest components of the Java platform), the java.lang.Math package, the ‘assert’ mechanism (amongst others) and indeed has gone on to greater stature and achivements as Principal Engineer (with special emphasis on being the Java guru in-house) at Google. I had heard of him before through his publications such as Effective Java, Java Puzzlers and Concurrency in Java and yet had never had the inclination (call it laziness if you will) to actually read past the titles. The thought that came to my mind was “Yet another Java book… how many of these darned things am I supposed to read before I actually master this constantly mutating platform?”. This bring to mind another powerful concept that made sense to me long after I had been exposed to it. It is called the ‘Paradox of choice’. The video is available here. It is an excellent talk by Barry Schwartz. Quite non-technical but I feel it has begun to be more pertinent to this industry than any other (and will only continue to be more so!). As it so happened, one lazy afternoon when I was casually browsing through some Google Techtalks online, I came across this rather innocuous sounding title – “How to design a good API and why it matters”. It would be a whole six months before I would watch that video!

When I finished watching that hour of pure technological operatic genius, my first reaction was that of dejection. Yes, dejection at seeing the video end so soon! The whole hour had gone off so smoothly and everything in the meantime just made such clear sense that it was nothing short of amazing. I had been deeply engrossed in some major coding work in my current project and wished that I had seen this video two months back! Uncannily though, I discovered, to my own smug contentment, that I had already followed most of the principles that were enunciated in the talk. Some of the pertinent points that he puts forth are as follows and struck me as particularly useful are as follows:

1. Whenever in doubt, leave it out!

This makes perfect sense. As he says, every programmer who develops at least a module is an
API developer because the methods and the public components of his module form the contract
for any clients that actually use his module. This maxim follows the logic that a component can
be added to an API later on, but can never be removed without breaking
existing functionality.This also implies that any ‘doubtful’ functionality can always be harnessed
on later.

2. The ideal size for a method paramater list is three or lesser. If there are more, split
them and/or use helper classes

The example that he provides (of a Win32 API call to draw a simple window) in the video says it
all. I found this principle very useful (in retrospect) when I was designing my modules (I will
have a series of blogs on that very soon) and was often in a bit of a quandary about the exact
scope of my utility methods. The requirements at that point of time were pretty
much solidified and yet the use-cases were not yet finalized. So it was more of a trade-off
between usability and genericity which leads us straight to the next
point.

3. If the API makes everyone equally happy and leaves everyone equally unsatisfied,
it’s done its job

It’s always a tight balance when designing an API – whether to make it extremely powerful (and
invariably for a select group of stakeholders) or to make it powerful enough (and
thus for the majority of the stakeholders). The latter is always preferred irrespective of the
scope of the applicability of the API. The case which is moot in this regard is the VMware API -
generic enough to be almost bloated and yet powerful enough to be used by any client. More
on the VMware APIs in upcoming weeks.

4. Exception handling is not just an escape mechanism but a means of controlling
the system flow

Now this is one part of the talk where Joshua could not allocate any time at all. Considering
that the whole hour-long talk was filled with absolutely no pauses and no wastage of time, this
goes to show how the topic deserved more time than the standard hour allocated for Google
Techtalks. Nonetheless, in my current project, this was the hardest nut to crack. Exception
handling is an even finer balancing act than the design of the contract of the modules (i.e., the
methods) as there is a huge state-space of possible control flow/ processing paths. The sad
truth is that this is often the part which is most often neglected. I, however tried to have a
fairly robust and generic mechanism whereby there was a Exception class
with a corresponding ERROR code interface, which was placed in a common module so as
to allow clients to access and throw specific error codes. The level of granularity is still being
refined as I find more use-cases and corner-cases. In my opinionated opinion, the design
of the exception handling mechanism is the true measure of good or bad design.

5. Document! Document! Document!

Joshua recommends documenting every class (what an instance of it represents), every method
(this forms the contract of the class after all!), every parameter and return type (mentioning the
types and units of the parameters). How important this is can be estimated by this
example – In my current project, I have over 400, 000 lines of Java code modularized into a
dozen projects and hundreds of packages and sub-modules. The real eye-opener is that there is
absolutely no documentation whatsover. Okay, that sounded harsh. Let me rephrase it thus -
There is not a single line of useful documentation. If it were not for my considerable
intellectual gifts and a generally consistent design, it would be impossible to decipher the whole
mish-mash much less augment the functionality!

6. Watch the video paisan!

In closing, I could go on about how profound my experience was watching this video and I could ramble on about about the merits of the whole experience (gosh, it’s almost sounding like I had a technological seance… which wouldn’t be far from the truth! ) but this post has already gone on too long and I am tired! Just kidding… I am busy in my epiphanic reading of ‘Effective Java’, ‘Java Puzzlers’ and ‘Concurrent Programming in Java’. Peace!