Intent-Revealing Interface

Kind: principle

Layer: Contracts Core

Aliases: Intent-Revealing API

Record: architecture:intent-revealing-interface

Severity: recommended

Scope: API, method, class, module

Canonical: Ontology

A design rule that an operation's name and parameters state what it does for the caller.

Listed in Architecture principles, after Ubiquitous Language and before Principle of Least Surprise.

Requires

• Clear Semantics
• Naming Consistency

Reinforces

• Principle of Least Surprise

Enables

• Readability
• Correct Usage

Conflicts with

• Ambiguous API
• Boolean Trap

In tension with

• Concise Naming

Tensions

• Intent-Revealing Interface / Concise Naming

Violated by

• Ambiguous API
• Boolean Trap

Refactored by

• Name the Concept
• Replace Boolean with Enum
• Value Object

Severity

• recommended

Category

• Schema / Canonical Data / Semantics

Enforced by

• rules/eslint/closure-register-verb-reserved.eslint.rule.ts
• rules/eslint/closure-registry-consumer-naming.eslint.rule.ts

Reinforced by

• Builder Pattern

Enabled by

• Ubiquitous Language

Linked from

• Anti-patterns
• Creational Patterns
• Schema / Canonical Data / Semantics
• Core Vocabulary
• Quality Attributes
• Schema / Canonical Data / Semantics
• Severity levels
• The resolutions