Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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

share|improve this question
Did you read the Wikipedia article (en.wikipedia.org/wiki/Principle_of_least_astonishment)? –  Doc Brown Feb 18 '13 at 15:35
Everybody's upvoting the comment but nobody's voting to close. This is a ridiculously open-ended question that's already clearly answered by reference sources; it doesn't belong on a Q&A site. –  Aaronaught Feb 19 '13 at 0:01
@Aaronaught open ended does not mean subjective, not constructive, nor off topic. There is possibly a single answer to the question that explains these concepts and its relationship with API design. –  MichaelT Feb 19 '13 at 0:08
@MichaelT and that is, no doubt, your answer which you've earned 120 rep for. What a surprise that you felt inclined to comment. Nevertheless, this is a general reference question that is at far too basic a level for a site that is ostensibly for expert programmers, and adds no value to either this site or the internet in general (since there is already a better explanation on Wikipedia). –  Aaronaught Feb 19 '13 at 0:12
@Aaronaught those able to upvote comments outnumber those able to VTC by over 100 to 1... –  AakashM Feb 19 '13 at 9:43

3 Answers 3

up vote 21 down vote accepted

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

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

share|improve this answer

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.

share|improve this answer
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 Rizos Feb 18 '13 at 15:54
For a definition of "WAT", please refer to this CodeMash 2012 conference destroyallsoftware.com/talks/wat –  Clement Herreman Feb 18 '13 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 Feb 18 '13 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. –  Joris Timmermans Feb 18 '13 at 16:25
@YannisRizos I just removed that link. I was just trying to get a small laugh in :) –  Earlz Feb 18 '13 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.

share|improve this answer
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. –  GalacticCowboy Feb 18 '13 at 17:26
While this is a nice story this is not an answer to the question. –  Marcel Feb 19 '13 at 11:27
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. –  Dave Clausen Feb 19 '13 at 14:51

Your Answer


By posting your answer, you agree to the privacy policy and terms of service.

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