Krzysztof’s Laws of API Design

Kryzstof Cwalina has written up some rules or “Laws” for API design, which I’m going to use in a presentation at some time in my company. I thought I should link them here in just in case I need to have to refer to it at that time. They are fairly good rules that I think should be used more often.

“usability” in this context means “how easy to use the library is”.

  1. The usability of a namespace is inversely proportional to the number of public types in the namespace.
  2. The usability of a type is inversely proportional to the number of public members of that type.
  3. The usability of a member is inversely proportional to the number of parameters this member has.
  4. The usability of a framework is inversely proportional to the sum of the number of explicit constructor invocations required and the number of types whose static methods need to be invoked to implement common scenarios.
  5. The likelihood of an abstraction being designed correctly is inversely proportional to the number of abstract members on that abstraction.
  6. The likelihood of an abstraction being designed correctly is proportional to the sum of the number of members taking it as a parameter and the number of types implementing it.
  7. The likelihood of a virtual member being designed correctly is inversely proportional to the size of the member’s body.
  8. The likelihood of a virtual member being designed correctly is proportional the sum of members calling it and the number of members overriding it.

Some of the comments were very interesting.

One commentator wrote:

If I understood correctly, applying laws 1, 2 and 3, the best class library in the world has:
one namespace
with one type
that has one member
with one parameter.
Or a member without parameters
or no members
or just an empty class library.
Sorry, I couldn’t resist 🙂

He had a point, which is why the original author decided to add the update, clarifying that the meaning of usability here means the “ease of use of a library”. Overall goodnes of a library is some combination of usability and functonality.

Read the rest of his blog.There’s prety interesting stuff about the
why the collections library of the .Net platform is theway it is.
Advertisements

Leave a Reply

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

WordPress.com Logo

You are commenting using your WordPress.com 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 )

Google+ photo

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

Connecting to %s

%d bloggers like this: