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.