Engineering and Framework Fever

Great article by Mike Taylor in this month’s PragPub magazine in which he examines the tension between hand-coding all of your application’s code and using libraries and frameworks.

Briefly summarized, the problems Taylor has with libraries are:

• bad quality,
• documentation that fails to explain what the library is about, and
• too many libraries to choose from with no guidance about their strengths and weaknesses.

This leads to a feeling of helplessness for programmers, as their work seems to consist mainly of plugging together third party code with varying degrees of success and elegance. Frameworks are particularly intimidating in this respect, as they take control over the flow of the program. This makes it hard to understand what is happening and why. On one hand, re-use is good engineering practice as it lets you focus on high-level problems, on the other hand, it is somewhat unsatisfying.

The best part of the article is that Taylor offers ideas on how to deal with this problem instead of just complaining. And the approach is not some unrealistic, back-to-the-roots suggestion that we all write our own search functions in machine language. His suggestions are formulated as what he calls a “two-prong manifesto”.

Prong 1: Simpler, clearer, shorter documentation. I have long felt that the common Javadoc (or RDoc, or doxygen, or whatever) format is suboptimal for understanding how to use a library, as it doesn’t tell you where to begin. Taylor suggests that a library should have a one-page overview. If a library cannot be summarized in a single page, it is to complex and should be redesigned.

Prong 2: Minimize the radius of comprehension. This one is more abstract, but possibly even more important. Taylor defines the radius of comprehension of a codebase as follows:

If you are looking at a given fragment of code, how far away from that bit of the code do you need to have in your mind at that time in order to understand the fragment at hand? It is a sort of a measurement of how good encapsulation is across the whole codebase, although when I say “encapsulation” here, I am using that term in a broad sense that means more than just technical issues such as what proportion of data members are marked private. I’m talking about a human issue here (and therefore, sadly, an all but impossible one to measure, though we know it when we see it).