If your API is confusing, change it!

Posted by Jeremy Miller on January 21, 2010

http://ayende.com/Blog/archive/2010/01/21/when-the-design-violates-the-principle-of-least-surprise-you.aspx

The MVC team really needs to go back and iterate on their validation
design and rethink it — and frankly, they need to have the courage to
challenge their approach and maybe even to break backwards
compatibility with the preview/CTP/beta/whatever they are’s if that’s
what it takes to make a better solution.

As an API designer, if your users are having consistent trouble with using part of your API, then your API is wrong.  Don’t try to beat it with just documentation or “user education.”  Go.  Change.  Your.  API.  To something that does work and makes your support queue slow down. 

The dumbest thing I ever did in StructureMap was something called the “StructureMapConfiguration” static class where everything had to be done in a certain, non-obvious order.  The best thing I ever did in StructureMap was to deprecate, replace it with a better API, it then kill it.  I get worlds of support questions, but at least *that* issue went away.

 

About Jeremy Miller

Jeremy is the Chief Software Architect at Dovetail Software, the coolest ISV in Austin. Jeremy began his IT career writing "Shadow IT" applications to automate his engineering documentation, then wandered into software development because it looked like more fun. Jeremy is the author of the open source StructureMap tool for Dependency Injection with .Net, StoryTeller for supercharged acceptance testing in .Net, and one of the principal developers behind FubuMVC. Jeremy's thoughts on all things software can be found at The Shade Tree Developer at http://codebetter.com/jeremymiller.
This entry was posted in Ranting. Bookmark the permalink. Follow any comments here with the RSS feed for this post.
  • http://codebetter.com/members/jmiller/default.aspx Jeremy D. Miller

    @Dave,

    That’s kind of the point of the FubuMVC effort. I sincerely don’t believe that the ASP.Net MVC codebase is a suitable foundation to build off of however.

  • http://snappyco.de Dave Newman

    Even better would be if the general community took some ownership, forked it (http://github.com/machine/msmvc/), fixed it and kept it moving ahead. There are a lot of smart people in the .net development community, it’s time to collaborate!

    BTW for a library/framework to stay useful and relevant, you will _have_ to break compatibility. People will fix their apps and they will be better off for it.

  • http://codebetter.com/members/jmiller/default.aspx Jeremy D. Miller

    @Sean,

    It might be bad if your code isn’t doing what you think it should be doing. You did read the part about the API in question not being officially released, right?

  • Sean Harney

    Maybe. But that might break backward compatibility with client applications programmed for the old API. This could be bad.

  • http://www.codephp.co.uk Adam

    I am writing an API (and a CMS) at the moment, and stumbled across the article.

    Any suggestions on “getting it right” first time, what makes a good api? what makes a bad one?

  • Andrew

    After reading Brad Wilsons pretty weak attempts to explain this, it’s obvious that there needs to be a new set of Attributes. Sometimes, you need to raise your hand and say “My Bad” and fix the problem. New Attributes won’t break existing code.

    Also, as an observer the “Hey don’t attach a model to the ORM even though every example we show you does it” is some funny stuff too. Another topic for another time.

  • http://codebetter.com/members/jmiller/default.aspx Jeremy D. Miller

    @Travis,

    It’s NOT the attribute that’s the problem at all. It’s their runtime model and the when/how/where that they do the “validation” that’s causing the problems. They have a design flaw that they need to correct that isn’t really about the name of “RequiredAttribute”

  • Travis

    @Andrew Pretty sure that attribute has been in the framework since 3.5 sp1. So it *is* in production ATM.

    See Brad’s update:

    http://bradwilson.typepad.com/blog/2010/01/required-doesnt-mean-what-you-think-it-does.html

  • Andrew

    Phil,

    You should probably look at the problem a little closer. In this particular case, the API isn’t even in “production” yet, so if Microsoft’s going to fix it, now is the perfect time. In a few months, it’ll graduate into the “10 years of support” category, and it’ll be annoying people for years to come.

  • http://blog.componentoriented.com D. Lambert

    Phil, I think the point here is that there are signs that an API publisher can look at to tell if the API is good or not, and when the API is bad, it should be fixed.

    Obviously, there are some borderline cases that may be better addressed with documentation, and you’re not going to just use one guy’s opinion to determine whether the API is good or not, but if you don’t deal with a bad API directly, you’re going to pay for it forever.

    Finally, don’t forget the last part of Jeremy’s post — you don’t just kill a bad API, you deprecate it. Then, you work on notifying users so they know it’s going away at some point, and only then do you actually kill it. This process can take a while to run its course, which is one of the reasons an API publisher will be reluctant to go this route.

    Trying to change the developer by throwing documentation at him is just arrogance on the part of the API publisher. At some point, the developers are going to find a better API and move to it.

  • http://michaelstechnical.blogspot.com Michael Hedgpeth

    Your recent update to StructureMap brought this home to me. It’s much better and took mere minutes to update. Good job following your own advice!

  • http://zoldello.wordpress.com Phil

    I do know much about the problem but given what I know I do not fault them. Microsoft has to support API for 10 years after it is released (or else its reputation for caring about developers and users take a hit [e.g like linq-to-sql getting replaced by entity framework-issue]) Making API cost money- usability test, developers, testers, big-shot executives need their hefty pay etc. You cannot just throw it away (aka deprecate it) just because Miller thinks (and is probably right) that the API sucks. You may think it is horrible but there are probably others that think it is the best thing since high-level languages replaced assembly language- sometimess what you like loses out when weighed against the majority. Beating the API with documentation and “user education” seems to be the best way to go.

  • http://blog.componentoriented.com D. Lambert

    Umm. Yeah.

    http://blog.componentoriented.com/2008/06/heres_a_clue_that_your_api_stinks/

    Bad API’s are sometimes hard to see when you’re developing them — after all, everything makes perfect sense to *you*, right? But when you start to get real feedback from real developers, that’s gold — don’t try to change the developers if they’re having trouble.

    I can’t tell you how many times I tried to buck this sort of feedback, and I was wrong every single time.