The principle of least surprise (sometimes known as the principle of least astonishment in more posh circles) is an axiom of design: typically UI design, but also software design. The idea is that some object, operation, device, etc, should be obvious and consistent with its name/appearance. A trivial example: a "left click" should be done by pushing the button farthest to the left on the mouse. To do otherwise would be quite surprising, and make for a bad experience. (That sounds shockingly simple, but it's just an example).

I was thinking about this when I was writing some validation code. I was thinking about a user selecting a U.S. State in a dropdown. On some forms, it's required for the user to select a State, on other forms it's optional.

I wrote a class to help me manage a list of States/Provinces like so:

Elsewhere, I wrote code to use the IsValidState method to check to see if the user, in fact, selected a valid state or not. The first time I did this, it was on a form where the field is required. So, if user doesn't select a state, then IsValidState wouldn't even get executed.

But, later on, I reused IsValidState on a form where the state field is optional. What happens when the state argument is null? A big fat exception, that's what. So, I changed the method:

Is that the correct decision? Or should IsValidState only be called when there's an actual value? I think I made the correct decision, because null isn't a State. Another decision that could be made is throwing an ArgumentException if the argument is null or empty. However, I don't think the correct decision was to leave the method the way it was.

So now let's enter the land of hypotheticals in order to think more about the principle of least surprise.

What if, instead of being a boolean function, IsValidState instead acted upon a StateArgs object being passed in (and its name was changed to ValidateState). Let's suppose there is some reason for this, and that part of the design is a given.  Suppose there's a Value string property with the State and an IsValid boolean property. (ASP.NET Validators, specifically CustomValidators, work like this: the validation method get an "args" object, and you can act upon it by manipulating args.IsValid). What would the correct behavior be then if args.Value is null? Clearly, args.IsValid shouldn't be set to true. So, should it be set to false, or should it just be left unchanged?

In this circumstance, ValidateState is probably one method call in a series of validation method calls (probably with some polymorphism involved with the parameter instead of a specific StateArgs class). So it seems like the least surprising thing to do would be to not make a decision (option A in the above source code). Since ValidateState does not return a value, it's not required to make a decision.