Principle of Least Astonishment (User & Future-You)

Great code and design should never surprise users or future developers—including yourself. The Principle of Least Astonishment means doing things the way people naturally expect, so nothing is confusing or unexpected.

When your code is predictable, it’s easier to use, safer to change, and more enjoyable to work on. Surprises in behaviour often lead to mistakes and wasted time.

Real-Life Analogy: The Odd Door in the Hallway

If every door in your office opens inward but one opens outward, someone will eventually get hit or confused. Code works the same way—if something is inconsistent, it will trip people up.

• Consistency keeps things safe and predictable.
• Small surprises can cause big problems.

Applying the Principle in Code

Follow common conventions and document any behaviour that’s different. Think about how you would expect it to work if you saw it for the first time.

• Use familiar names and structures.
• Keep patterns the same across your codebase.

Common Mistakes

Avoid clever “tricks” that make code behave differently from what its name or shape suggests. Tricky code confuses both users and your future self.

• Don't surprise users with hidden side-effects.
• Make behaviour as obvious as possible.

Final Thoughts

Write code that feels natural and is free of surprises. Your users—and your future self—will thank you.