Martin Pool's blog

Rusty on Interface Simplicity

Rusty's OLS 2003 keynote looks at the problem of designing and defining interfaces between software modules. For large programs, this tends to be a more important issue than the design of any one module, for a few reasons. Modules can be rewritten, but changing an interface can destabilize the whole system. You can get away with only one or a few programmers understanding the internals of a module, but almost by definition interfaces need to be understood by more people:

Once the code gets too big for one person, it's all about damage control. Interfaces make damage control possible... except when the interfaces themselves are the problem.

Rusty says the key criteria for an interface is how easy it is to use correctly or (by Murphy's Law) how hard it is to misuse. He delineates a spectrum from best to worst, which is so good I am going to shamelessly reproduce it here:

1. Compiler/linker won't let you get it wrong.

2. Compiler will warn if you get it wrong.

3. The simplest use is the correct one.

4. The name tells you how to use it.

5. Do it right or it will break at runtime.

6. Follow common convention and you'll get it right.

7. Read the documentation and you'll get it right.

8. Read the implementation and you'll get it right.

9. Read the correct mailing list thread and you'll get it right.

10. Read the documentation and you'll get it wrong.

11. Follow common convention and you'll get it wrong.

12. Do it right and it will break at runtime.

13. The name tells you how not to use it.

14. The obvious use is wrong.

15. Compiler will warn if you get it right.

16. Compiler won't let you get it right.

17. It's impossible to get right.

When you're inventing an interface, see if you can shift it up this list one or more steps. In particular, think about whether bugs are caused by interfaces that are too far down the list.

A favourite example of perverse interface design is bogofilter inverting the meaning of two flags from one release to the next.

Linus's law should have prevented that: if you change the meaning of an interface, change the name as well. In this case, if you feel the you assigned the wrong action to the -n option in the first release, then don't just change it. Make that option deprecated or invalid, and assign the new action to some other action. Years later you might reuse that option, once you're sure everyone has forgotten the original meaning, but even that is risky.

Archives 2008: Apr Feb 2007: Jul May Feb Jan 2006: Dec Nov Oct Sep Aug Jul Jun Jan 2005: Sep Aug Jul Jun May Apr Mar Feb Jan 2004: Dec Nov Oct Sep Aug Jul Jun May Apr Mar Feb Jan 2003: Dec Nov Oct Sep Aug Jul Jun May