Extreme Advice Considered Harmful

From APIDesign

Revision as of 15:18, 23 January 2009

Have You Ever Wondered...?

I've just finished reading the theoretical and practical parts of your book, are you saying me that I have to apply all your advices to be successful? No, not at all. One of the the worst things to do is to follow advice completely, to the extreme. The chapter 13 builds on the Considered harmful phrase and expands it meaning into the world of API Design.

API has to be Correct

One of the advices that can often cause more harm than be useful, is the attempt to make an API fully correct. Well, nothing about correctness, correct version of an API is better than incorrect one, in case all other features of those two versions are on par. But often, in the search for correctness one sacrifices simplicity.

An example of this can be found in Java's java.io.File. Have you ever tried to read a content of a file in Java? Painful, isn't it? Instead of having a single method to load file's content into a String, one needs to allocate an array, write a loop to populate it and only than convert it into so desired String. I wrote that code many times, especially as a utility method in a unit test, so I at least know how to do it. However imagine a newcomer, a refugee from Perl, trying to rewrite a single line of such I/O Perl code to Java. How can such trivial task be so complex!? Why we cannot have simple methods like:

File f = new File("config.txt");
String text = f.asText();
byte[] arr = f.asBytes();
for (String line : f.asLines()) {
  ...
}

I explain this unnecessary complexity as a result of an extreme search for correctness. Plus a little bit of copy based design. Reading done in the Java way almost completely mimics the C style. E.g. malloc a bit of memory, read data into it, process them, read additional data, etc. This C way is known to be correct, never exhaust available memory and be robust even for use in operating systems. As such the designers of the Java I/O libraries just copied this correct and well-working principle.

Nobody of its designers considered it too complicated, as they were familiar with it from their C days. In fact it is not that complex compared to other C constructs. Just try to concatenate two C strings and you'll find out how verbose that code is. The C libraries leave the memory manipulation up to the programmer. However Java is different, concatenating strings is a matter of single +. Memory is allocated and freed automatically as needed. API users usually do not need to care. And they like it. As such the Java I/O API for reading from a file seems like a relict of stone age. So complex and hard to use (but correct).

For a while I was advocating the Java I/O library to be enhanced with simple reading utility methods. However that takes time. But a few weeks later I realized that we do not need to wait! The NetBeans project has own virtual filesystem library and we can add the methods there! Today I started an API Review to provide simple I/O reading API (see issue 157362).

Users of NetBeans 7.0 APIs, say farewell to painful reading of files! And please accept my apology for using copy based design and realizing only recently that our users could benefit from our own asText(), asBytes(), and asLines methods.