# Principle of Least Surprise

> A design rule that an operation behaves the way its name and its conventions lead a caller to expect.

Record: `architecture: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#architecture-principle-of-least-surprise

Listed in [Architecture principles](https://banes-lab.com/api/records/architecture.md), after [Intent-Revealing Interface](https://banes-lab.com/records/architecture/intent-revealing-interface.md) and before [Database Normalization](https://banes-lab.com/records/architecture/database-normalization.md).

## Repair

- Refactored by: Rename, Make Side Effects Explicit, Normalize Behavior
- Detected by: misleading names, [hidden behavior](https://banes-lab.com/records/lexicon/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/lexicon/tests.md)

## Requires

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

## Reinforces

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

## Enables

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

## Conflicts with

- [Hidden Side Effect](https://banes-lab.com/records/architecture/hidden-side-effect.md)

## In tension with

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

## Tensions

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

## Contracts

- [Human Factors](https://banes-lab.com/records/algorithms/human-factors.md)

## Severity

- [recommended](https://banes-lab.com/records/vocabulary/severity-recommended.md)

## Category

- [Schema / Canonical Data / Semantics](https://banes-lab.com/records/architecture-category/schema-canonical-data-semantics.md)

## Enforced by

- [rules/eslint/closure-show-flag-polarity.eslint.rule.ts](https://banes-lab.com/source/governance/rules/eslint/closure-show-flag-polarity.eslint.rule.ts.md)

## Reinforced by

- [Uniform Interface](https://banes-lab.com/records/architecture/uniform-interface.md)

## Linked from

- [Anti-patterns](https://banes-lab.com/ontology/principles/architecture-category-anti-patterns.md)
- [Contracts / Interfaces / Compatibility](https://banes-lab.com/ontology/principles/architecture-category-contracts-interfaces-compatibility.md)
- [Correctness / Determinism / Verification](https://banes-lab.com/ontology/principles/architecture-category-correctness-determinism-verification.md)
- [Schema / Canonical Data / Semantics](https://banes-lab.com/ontology/principles/architecture-category-schema-canonical-data-semantics.md)
- [Schema / Canonical Data / Semantics](https://banes-lab.com/ontology/lexicon/lexicon-category-schema-canonical-data-semantics.md)
- [Architectural Clusters](https://banes-lab.com/ontology/algorithms/algorithms-domain-architectural-clusters.md)
- [Severity levels](https://banes-lab.com/ontology/schema/the-vocabulary-severity.md)
- [The resolutions](https://banes-lab.com/ontology/schema/the-resolutions.md)