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" ?


4 Answers 4


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):

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

  • 5
    Good answer. Put simply the PoLA means a design should both create expectations and fulfill those expectations. It should do pretty much what people expect it to do. Commented Aug 23, 2015 at 21:13
  • The IBM developer blog seems to have been reorganiserd - the link is no longer working, nor is the PDF download available. Maybe someone can get an archive.org link for it, or similar?
    – Jaap
    Commented Mar 19, 2019 at 13:08

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(){
} //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.

  • 3
    That blog post is full of bs, and pointing at it isn't exactly helpful (even if it wasn't full of bs). You should remove it and point to specific examples of PHP's inconsistencies (there are so many of them, it won't be hard to chose a couple).
    – yannis
    Commented Feb 18, 2013 at 15:54
  • For a definition of "WAT", please refer to this CodeMash 2012 conference destroyallsoftware.com/talks/wat Commented Feb 18, 2013 at 16:06
  • I agree with your examples except the DateTime thing. I assume it's an immutable object and Add returns a new instance. This is quite common.
    – musiKk
    Commented Feb 18, 2013 at 16:07
  • @musiKk - it's only common in languages where it's not even MORE common to expect modifying side-effects from calling member functions. Astonishment is context-sensitive. Commented Feb 18, 2013 at 16:25
  • @YannisRizos I just removed that link. I was just trying to get a small laugh in :)
    – Earlz
    Commented Feb 18, 2013 at 16:29

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.

  • I had a GPS app that couldn't identify the specific address that I wanted (in an unfamiliar city) so it just gave me directions to the center of downtown. Fortunately, Google Maps figured out from there that my destination was only a couple miles away. Commented Feb 18, 2013 at 17:26
  • 4
    While this is a nice story this is not an answer to the question.
    – Marcel
    Commented Feb 19, 2013 at 11:27
  • 1
    Fair enough. The question asked for help understanding a concept. At least for me, examples always help with this. The question also asked how the concept permeates beyond; which I tried to answer. Commented Feb 19, 2013 at 14:51

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)

  • 1
    this doesn't seem to offer anything substantial over points made and explained in prior answers that were posted many years ago
    – gnat
    Commented Apr 26, 2020 at 15:06

Not the answer you're looking for? Browse other questions tagged or ask your own question.