Hiatus (agh) wrote,

"When in doubt, leave it out."

Joshua Bloch, who worked extensively on the Java library, said this in his lecture on API usability at OOPSLA last year.  He was referring to the idea that, if you don't have a clear scenario and testing for a method, don't include it in your API.  You can always add later, but once you put something in, you have to support it and can never remove it.  Also, ill-conceived "kitchen sink" APIs tend to be cluttered, and offer little in the way of guidance on where to begin in the common scenarios.  They also tend to require lots of boilerplate code: long strings of function calls with no input from the client.  If there's no input, why not wrap them up into a function that calls all of them?

For me, his comments solidified something I'd been saying to my teammates, in less crisp and concise terms, for some time, and was a touchstone I began to use when talking to people about choices around APIs.

From the other side of the universe, some of the people on my old team lived in fear that if they didn't expose everything publicly, someone somewhere would want to do something that they couldn't do, and this would be disastrous.  They would often make dire compromises for that principle, including exposing what would normally be construed as implementation details.

Once you expose your implementation, you are locked into that implementation, and can no longer change as new requirements such as performance, scalability, and security come into play in future versions.

The situation is exacerbated by the fact that, in many programming languages, it's simply easier to make something public than private.  This is helped somewhat if you use tools like C#'s Xml docs, and .NET's FxCop which force you to do extra work on public interfaces to make them presentable.  They impel you to really think about what you're doing.

I'm catching more whiffs of this desire to expose everything down to the metal, despite the sheer impossibility of testing/supporting/maintaining that low-level surface.  But even C++ developers badly need constraints and guidance, such as type safety and other static checking, convenience wrappers, and aggregates.  If something is left out, at least they will know it quickly and look for other solutions.  Often times, a kitchen sink API seems like it will support the client's scenario, only for them to find out it wasn't really that well supported and there are bugs, or worse, it changes in the next version and breaks their application.

The compromise I typically hear is "Make the common stuff easy, and the uncommon stuff possible."  This sounds reasonable at first, but unless you're very careful, you're still exposing a bunch of stuff you probably haven't done focused testing on, and you're going to be right back in the application-compatibility hell that Windows is doomed to for all eternity.

I'm still working out the tradeoffs here, and meanwhile trying to figure out how to communicate with people who come from the other side of the universe.
Tags: code

  • Windows 7

    Windows 7 is coming out in beta this weekend. It's a no-brainer upgrade from Vista, as it is, for my purposes, a strictly superior OS. And if you're…

  • Pro and Repro were sittin' in a boat... Pro fell out, who was left?

    So, I'm debugging this issue with the tooltips in the Windows common controls. A particular debugger is crashing when it's trying to display the…

  • F#MiniJava

    Sunday, Chris and I finished our minijava compiler implementation in F#. Whereas most of the class implemented it in Java or C#, we knew that all we…

  • Post a new comment


    default userpic
    When you submit the form an invisible reCAPTCHA check will be performed.
    You must follow the Privacy Policy and Google Terms of use.