Wed 9 Jan 2008

API Design -- The Rusty Levels

Rusty Russell's Hard To Misuse Interface Levels

Lower numbers are better. Really. Source is here. See below for details.

1. It's impossible to get wrong.
2. Compiler/linker won't let you get it wrong.
3. Compiler will warn if you get it wrong.
4. The simplest use is the correct one.
5. The name tells you how to use it.
6. Do it right or it will always break at runtime.
7. Follow common convention and you'll get it right.
8. Read the documentation and you'll get it right.
9. Read the implementation and you'll get it right.
10. Read the correct mailing list thread and you'll get it right.
11. Read the documentation and you'll get it wrong.
12. Follow common convention and you'll get it wrong.
13. Do it right and it will break at runtime.
14. The name tells you how not to use it.
15. The obvious use is wrong.
16. Compiler will warn if you get it right.
17. Compiler won't let you get it right.
18. It's impossible to get right.

Background

Back in July, 2003, Rusty Russell gave the keynote address at Ottawa Linux Symposium. Rusty's a great speaker and normally selects excellent topics that are technically informative, whilst being entertaining even to those who may not have a deep understanding of the details. Anybody who has a chance to see him speak should drag themselves on their knuckles over hot coals to get there.

I could go on for days about the things I've learnt from Rusty's talks (always bring a good book, sit near an exit so you can leave early if it's boring ... no, seriously now... ), but I won't. Suffice it to say, they're worth the effort to attend.

This particular talk, Hanging Out With Smart People (Things I Learned Being A Kernel Monkey) is available online in that highly portable and somewhat impractical format known as jpeg images. Go read it. Now!

Unfortunately, the format does lend itself to searching and so his very useful list of programming interface levels of usefulness has been lost to Google. I really wanted to quote this list today in a mailing list discussion, so, here for the benefit of search engines is Rusty's list. It should be noted that the talk contains an example from the linux kernel for each of these, except the last one (thankfully).

Topics: software/design, software/linux