A note on interface design

While reviewing some code today, a principle of software design somehow distilled itself to clarity in my head.

When designing your system, think of every major system1 upon which your own system directly depends2 as a bug.

By “think of it as a bug,” I mean that sooner or later, you are going to come to truly hate this dependency. It won’t do what you want, or it will turn old and crufty, or it will get outdated, or your system will outgrow it. Perhaps it already stinks. And therefore, think about what you are going to have to do to take it out and replace it with something better, and possibly not even having similar API’s.
Yes, you should have your code sufficiently factored and modular that such a replacement will be minimally invasive. But more importantly: if that replacement requires any change in the API’s3 by which the outside world is using your system, then there is something wrong with your design. Stop and fix that immediately.

1Both external dependencies and major subsystems of your own code. Both will suck in time, I promise you.
2If the systems upon which you directly depend have done this properly, you don’t need to worry about your indirect dependencies. If they haven’t, then you should consider replacing them now, because you are obviously dealing with the work of madmen.
3Or UI’s, if your software is at the top of its software stack. UI’s are just API’s for communicating efficiently with humans. (Or perhaps API’s are just UI’s for communicating with computers?)

Advertisements
Published in: on March 18, 2010 at 20:45  Comments (7)  
Tags: ,

7 Comments

  1. Dependencies can definitely be problematic. But I would make a minor modification to your principle: I’d treat each dependency as a potential source of bugs.
    Not all dependencies are created equal. I wouldn’t want a principle that argued against factoring a large, complex, buggy system into several smaller, simpler, less buggy ones, just because it increased the number of dependencies.

  2. Dependencies can definitely be problematic. But I would make a minor modification to your principle: I’d treat each dependency as a potential source of bugs.
    Not all dependencies are created equal. I wouldn’t want a principle that argued against factoring a large, complex, buggy system into several smaller, simpler, less buggy ones, just because it increased the number of dependencies.

  3. UI’s are just API’s for communicating efficiently with humans.
    Plus
    By “think of it as a bug,” I mean that sooner or later, you are going to come to truly hate this dependency.
    Equals everyone hating every piece of software they use eventually. Tell that to emacs zealots.
    Also, working at Google has the effect of exposing one to fast moving and quickly cruft accumulating APIs. There seem to be well-tested APIs that pretty much do what they advertise, and are rarely, if ever, changed in meaningful ways.
    (Jeremy M)

  4. Oh, definitely! I don’t mean that the dependency itself is a bug; rather, that it’s helpful to think of the component underneath the dependency as something you will want to swap out sooner rather than later. The principle is really just against API leakage.

  5. There seem to be well-tested APIs that pretty much do what they advertise, and are rarely, if ever, changed in meaningful ways.
    And those are beautiful, beautiful things. Which tend to have this property as well — that they’re very independent of their underlying systems.

  6. Oh, that’s lovely.

  7. While I agree with the sentiment, Google therefore has some of the buggiest software projects and systems I’ve seen in my life.


Comments are closed.

%d bloggers like this: