The Principle of Least Surprise

Principle of least surprise: photo of a very surprised woman

The Principle of Least Surprise (POLS), also known as the Principle of Least Astonishment (POLA), is a design guideline for both software and user interfaces. It says that every component in a system should behave in a way that most users expect it to behave, and therefore not surprise or astonish them. These components could include an action in a user interface, a class, a method in a class, or a API call in a web service.

Users should be able to anticipate the behaviour of a system, based on their previous experiences with similar systems. The behaviour of a system must be consistent with the user’s idea of how that type of application should work.

In the book The Art of Unix Programming, Eric Steven Raymond said, “In interface design, always do the least surprising thing.”

User Interface Design

The Principle of Least Surprise is used in user interface design to make sure that the application is intuitive and easy to use.

For example, if a user clicks the “Save” button, they would expect the system to save whatever they wanted it to save. If the button discarded or deleted their work, this would be surprising and frustrating for the user. Such unexpected behaviour would definitely cause unhappiness with the application. Eventually the users could stop using it, and probably want their money back. In these days of internet reviews, we don’t want our product to get any bad reviews.

Don’t ignore a user who reports that a system feature behaves in a way that is surprising or unexpected. Instead, use that feedback to make the system more user-friendly.

Software and API Design

We use the Principle of Least Surprise in software design as well, not just in front-end user interfaces.

An API (application programming interface) should behave exactly as the user expects it to behave. We have to think about how the user would want to use the API. We should never surprise the user. If the user is surprised by anything the system does, we should redesign those parts of the system. Unpredictable system behaviour is unwanted and annoying.

A class, method or API call should do the most obvious thing the user should expect from its name. Method and API calls should never have unexpected side effects. If a method is called log(String message), it should log the message and not also redraw the screen and mow the lawn.

The following method would be terribly surprising and cause havoc:

public int add(int a, int b) {
    return a * b;  // anything other than a + b would be bad!

Being clear and obvious is one of the keys to clean, predictable code. We need to use obvious names with expected return types. The easy solution is to use the most obvious, explanatory names for classes, methods, functions and API calls.

For more information on clear name usage, see the three blog posts on naming things.

  • Part 1 covers Java identifiers and naming conventions.
  • Part 2 covers Hungarian notation and abbreviations (a big no-no!) and using units in names.
  • Part 3 covers class and interface naming.

Command-Query Separation (CQS)

The Command-Query Separation (CQS) Principle goes hand in hand with the Principle of Least Surprise. CQS suggests that we should separate methods that change an object (commands) from methods that ask the object a question (queries). Query methods only retrieve data and command methods can modify data. Asking a question should not change the answer.

Every method should then be either a command that performs an action, or a query that returns data to the caller, but not both. A query method should not change the observable state of an object.

By not changing the state of an object when querying it leads to fewer coding surprises. Think of a REST web service. A GET call should only retrieve (query) an existing resource, and not do anything else with the resource. A PUT call should update the existing resource (and not retrieve data). A POST call should only create a new resource. A DELETE call should only delete an existing resource.


In summary, the Principle of Least Surprise is an important design guideline. A system should behave in a way that is consistent with the user’s expectations of how the system should work.

What experiences have you had with surprising interfaces or software? I’d love to hear your examples.

Leave a Comment

Your email address will not be published. Required fields are marked *

Code like a Java Guru!

Thank You

We're Excited!

Thank you for completing the form. We're excited that you have chosen to contact us about training. We will process the information as soon as we can, and we will do our best to contact you within 1 working day. (Please note that our offices are closed over weekends and public holidays.)

Don't Worry

Our privacy policy ensures your data is safe: Incus Data does not sell or otherwise distribute email addresses. We will not divulge your personal information to anyone unless specifically authorised by you.

If you need any further information, please contact us on tel: (27) 12-666-2020 or email

How can we help you?

Let us contact you about your training requirements. Just fill in a few details, and we’ll get right back to you.

Your Java tip is on its way!

Check that is an approved sender, so that your Java tips don’t land up in the spam folder.

Our privacy policy means your data is safe. You can unsubscribe from these tips at any time.