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 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 a 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 separate 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

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.

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.

In simple words, POLA i.e Principle of Least Astonishment means your API, UI, etc. should work as a user would expect it to work normally.

For example, When a user fills out an online form & clicks on OK button, he might expect to see a response like : “Your info was saved”, or maybe “Done”, etc.

But if you directly log him out by showing him a message – “Logged out, Thanks”,
the user will obviously be astonished.

(Here, it might be actually possible that the developer logic was correct considering it was the last page of the form & logically the user had to be logged out.
But still, as per POLA, it would have been great if the user was atleast informed that his data is saved)