The true raconteur and I ain’t talking about Feynman!

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

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!


15 thoughts on “The true raconteur and I ain’t talking about Feynman!

  1. > 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. He’s called a raconteur because of the exciting way in which he recounted (see the etymological kinship?) anecdotes of his life. The epithet has nothing to do with his brilliance in explaining physics.


  2. Oh my gosh…I was grabbed to your blog by the title – it’s mention of Feynman because I’m a fan of the tv show “Numbers;” but then I started reading and you are a gifted writer. Now, I don’t understand most of what you’ve written, but since my husband is a senior software engineer and he comes home grumbling and disgusted because people before him on certain projects did not document, it costs him valuable time and energy. Anyway, this was definitely interesting reading!


  3. @Web Design company

    You are right in the etymological reasoning. However, I am aware of that connotation and hence the structuring of the sentence as “… because of his extremely direct manner of explaining, in the simplest of terms…” which would refer to the same sense of the term that you are implying. Insofar as the reason why he was called a “raconteur” is concerned, I would beg to differ – his ability to ‘recount’ and rephrase complex theorems in much simpler terms was what earned him this epithet. No doubt that he had the ability to regale folks with his stories and anecdotes but that was part of his persona rather than something that he earned!


  4. @lindasnbusiness

    Thanks for the appreciative comments! I can definitely sympathize with your husband there! In fact I have seen (otherwise) brilliant programmers simply finish the most enjoyable part (coding) and then conveniently forget that there are folks who have to maintain that code and they would need decent documentation to save a lot of time, money (and brownie points on their BP!).


  5. @MB

    Hehehe…. in fact, I was writing this article in between work and after finishing the firt paragraph, I had to complete it before I could do any more work! Guess it’s my way of showing respect to the few genuine software geniuses left out there! Thanks for the appreciation.


  6. It’s strange to be praising Feynman when your own writing is pompous verbiage. Is this intentional?

    If not, I strongly suggest reading Orwell’s “Politics and the English Language” and at least skimming Strunk & White’s “Elements of Style”. Both are freely available on the web.


  7. @Irrelevant

    My contention is this: There is a certain level below which any expression of language would be (and aptly so) considered ‘sub-standard’. That’s the maxim I choose to follow. While you have completely missed the point of the blog itself, I would like to thank you for the two excellent recommendations indeed! I just finished reading Orwell and while I do not agree with all his points, some of them are worth imbibing and implementing in practice. As an aside, three places where your alleged ‘pompous verbiage’ comes useful:

    1. Sarcasm.
    2. Confabulation and
    3. Mischief.



Speak your mind!

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s