What is the principle of least astonishment?

Question

In programming what is called Principle of Least Astonishment? How is this concept related to designing good APIs? Is this something applicable to only object oriented programming or does it permeate other programming techniques as well? Is this related to the principle of "doing a single thing in your method and do it well" ?

Answer 1

The Principle of Least Astonishment is applicable to a wide range of design activities - and not just in computing (though that is often where the most astonishing things happen).

Consider an elevator with a button next to it that says "call". When you press the button, the payphone phone rings (rather than calling the elevator to that floor). This would be considered astonishing. The correct design would be to put the call button next to the phone rather than the elevator.

Next, think of a web page that has pop up window that shows a windows style error with an 'ok' button on it. People click the 'ok' button thinking it is for the operating system and instead go to another web page. This astonishes the user.

When it comes to an API...

• Think about a toString() method that instead of printing out the fields returns back "to be implemented".
• An equals() method that works on hidden information.
• Sometimes people try to implement a sorted list class by changing the add method to call sort() on the array afterwards - which is astonishing because the add method is supposed to append to the list - this is especially astonishing when one gets back a List object with no knowledge that somewhere deep inside, someone violated the interface contract.

Having a method that does one distinct thing contributes to reduction of astonishment, however these are seperate principles in API design. The four principles often touted as "good API design" are (from this pdf - just one instance of such a presentation. The links at the end of this particular one make for good reading):

• Single responsibility principle
• Open closed principle
• DRY
• Principle of least astonishment

It is potentially astonishing for someone to have a class that tries to do everything - or needing two classes to do a single thing. It is likewise potentially astonishing for someone to mess with the internals in odd ways under the covers (I find open classes in ruby to be a source of never-ending astonishment). It is also likewise astonishing to find two methods that do apparently the same thing.

As such, the principle of least astonishment underlies the other API designs - but it, itself, is not sufficient to simply say "don't have an astonishing API."

Further reading (from the UI perspective) - an IBM developer blog titled The cranky user: The Principle of Least Astonishment

Answer 2

Principle of least astonishment is when you, as an API designer, prevent your users from saying WAT.

Some examples of astonishment in varying languages.

var array=new string[]; 
var list=array as IList<string>; //this works... 
list.Add("foo"); //exception saying it's not supported

foo.Equals(bar); //will call overriden Equals method
foo == bar; //equivalent to above in everyway, except for it won't call overrides... unless you're dealing with a string

var d=DateTime.Today;
d.Add(new TimeSpan(36,0,0,0)); //add 36 days to datetime d
Console.Writeline(d); //will print todays date. WAT

//in javascript
var f=function(){
  return 
    10; 
} //will either throw a syntax error or return void, depending on your javascript runner

And there are many more examples in various languages and APIs. Your job as an API writer is to prevent this. Things should be named and typed in such a way that it's blatantly obvious what a call to your API will do. Include ample documentation where this isn't possible.

Basically, if people have to read your documentation thoroughly to figure out how to READ code written for your API, you're probably doing it wrong.

Answer 3

Here's an example of "astonishment" that happened to me recently. I got lost on the road, so pulled over and somewhat frantically (I was late) punched an intersection into my GPS. I clicked Go and put my hands back on the wheel - but then got a loud (full-screen) warning that the GPS should be updated - requiring me to acknowledge.

My thought was "are you kidding? you're telling me this now? I need to take my hands off the wheel to acknowledge?".

Astonishment surfaces in the interface (typically the UI, but I suppose it could also be an API that behaves in an unexpected manner). I would say it permeates below the interface as well, because it takes well-designed underlying software to support a truly well-designed interface.