# Principle of Least Surprise

Record: `arch:principle-of-least-surprise`
Kind: principle
Layer: [Contracts Core](https://banes-lab.com/records/layer/contracts-core.md)
Severity: recommended
Scope: API, UX, module behavior
Canonical: https://banes-lab.com/ontology#arch-principle-of-least-surprise

## Repair

- Refactored by: Rename, Make Side Effects Explicit, Normalize Behavior
- Detected by: misleading names, [hidden behavior](https://banes-lab.com/records/lex/hidden-behavior.md)
- Violated by: unexpected mutation, nonstandard behavior
- Measured by: surprise defects, misuse reports
- Enforced by: API review, [tests](https://banes-lab.com/records/lex/tests.md)

## requires

- [Predictability](https://banes-lab.com/records/arch/predictability.md)
- [Convention](https://banes-lab.com/records/lex/convention.md)

## reinforces

- [Stable Interfaces](https://banes-lab.com/records/arch/stable-interfaces.md)
- [Intent-Revealing Interface](https://banes-lab.com/records/arch/intent-revealing-interface.md)

## enables

- [Safe Use](https://banes-lab.com/records/lex/safe-use.md)

## conflicts-with

- [Hidden Side Effects](https://banes-lab.com/records/lex/hidden-side-effects.md)

## tensions-with

- [Clever Abstractions](https://banes-lab.com/records/lex/clever-abstractions.md)

## tensions

- [Principle of Least Surprise Clever Abstractions](https://banes-lab.com/records/tension/clever-abstractions-principle-of-least-surprise.md)

## referenced-by

- [Uniform Interface](https://banes-lab.com/records/arch/uniform-interface.md)
- [Predictability](https://banes-lab.com/records/arch/predictability.md)
- [Intent-Revealing Interface](https://banes-lab.com/records/arch/intent-revealing-interface.md)