More software engineers would heed the Principle of Least Astonishment.
“A component of a system should behave in a way that most users will expect it to behave, and therefore not astonish or surprise users.”
This principle emphasizes reducing cognitive load for developers.
When it’s ignored, developers waste time dealing with:
- misleading function names with hidden side effects
- unhelpful error codes
- inconsistent APIs
- configuration scattered in unexpected places
- irregular or contradictory architecture patterns
When systems behave as developers expect, they can focus on building features instead of deciphering the system.
Related: 2025-07-19-ai-agents-problems