What makes an API good

Today, once again, one of my colleagues called me to his desk and asked why the following code did not work as expected:

Debug.WriteLine("Message received: {0}", receivedMessage);

It should print out something like "Message received: Hello", right?

I've seen someone else have this problem before, and I myself did run into it.

- Look at the infotip. The first param is the message, and the second one is its category.

- Uh oh, category. How could I miss that!

I know why. He, as well as me and many other developers, expect Debug.WriteLine to work the same way as Console.WriteLine; so much that we do not notice the infotip's contents. Because Console.WriteLine is too well-known, I consider the signature of Debug.WriteLine bad design.

Good API is intuitive. The key to that is being consistent with well-known and widely used patterns. It is ideal if developers could code without looking at the documentation. Although computer is getting faster, it still takes some time to load the documentation. That reduces productivity and tests the developer's mentality. Thanks to good modern IDEs, we now less and less have to consult documentation. The usual reason I still have to look at the doc is to check out the Exceptions section. Of course, sometimes I have to consult the other information like thread safety, remarks, examples, etc. - but that is for more complex API when looking at the documentation is necessary.

I always wish that the IDE should somehow let users view exception information, at least for system types, in some form of intellisense dialog. It could do this by parsing the XML comments. The pitfall of this is that it might mislead the developer to trust that exception information which will certainly cause troubles if the method is poorly XML documented (it might still be documented well in some form else, but not XML comments). Exception documentation is just a good practice, not a contract. Java has experimented exception specification, with some benefits and some drawbacks. I am thinking of some solutions, like ExceptionAttribute, but none of them really helps.

Nevertheless, a good API should expose as much useful information as possible, in form of contracts, metadata (attributes), or at least standardized comments/documentation. Consistent style, self-documented names, commonly-used members/features emphasized. Good API + good IDE save developers' lives.

Why exception so verbose?

I remember, on my first days with VS.NET, I wanted to add some exception classes to my project. I launched the Add New Item dialog trying to find some item like exception. There was no such item (it even did not have an item for interface! - VS2005 fixed this). I had to add a regular class, typed in the code for its standard constructors, then copied and pasted to create other exception classes. Although my application used a bunch of exceptions, none of them contained additional fields or methods - just the standard constructors. The way current languages support exception make exception's type so important and often solely adequate.

Later, I figured out how to add a template into VS.NET and made it appear on the Add New Item dialog. Since then, I did not have to manually type the exception code again (except for the infrequent case when I want to add some extra stuff into the exception).

However, every time I look at the code of a "standard" exception, I keep asking myself why on earth it has to be so verbose? Wouldn't it be neater to be one-line concise like this:

public exception MyException;

or if the exception should have a parent other than System.Exception:

public exception MySpecificException: MyException;

The compiler will compiles it into a "standard" exception. This is essentially the way delegate keyword in C# works.

Then you and me - the code typists - will have some time for a cup of tea.