Pattern
Functional Transparency
How something works should be evident. No mystery. No magic. Exposed structure like Eames chairs. Self-documenting code. Honest materials.
"Good design makes a product understandable."
— Dieter Rams, Principle 4
Definition
Functional Transparency means the mechanism is visible. You can see how it works by looking at it. The Eames LCW chair exposes its plywood layers. A well-written function reveals its purpose through its name and structure.
This is Rams' fourth principle made concrete: the product clarifies its own structure. No hidden complexity. No "magic" that mystifies. The user (or developer) can trace cause to effect without documentation.
In architecture, this means exposed steel and visible joinery. In software, it means self-documenting APIs, clear dependency graphs, and code that reads like prose. The structure is the documentation.
"If you have to explain it, you haven't made it transparent enough."
Principles
Expose Structure
Don't hide how things connect. Show the joints. Reveal the dependencies. The Pompidou Centre puts its pipes on the outside. Your architecture should too.
✓ Visible folder structure matching mental model
✓ Clear import paths showing relationships
✓ Architecture diagrams derived from code, not imagined
Name Things Honestly
Names should describe function, not obscure it. A function called processData is opaque. calculateMonthlyRevenue is transparent.
✓ Verb + noun naming (getUserById, sendNotification)
✓ No abbreviations that require lookup
✓ File names that predict contents
Honest Materials
Use materials for what they are, not to simulate something else. Concrete should look like concrete. A database should behave like a database.
✓ HTML for structure, CSS for style, JS for behavior
✓ Types that reflect actual data shapes
✓ APIs that expose, not hide, underlying capabilities
Eliminate Magic
Every "magical" behavior should be traceable. If something happens automatically, the trigger should be visible. No spooky action at a distance.
✓ Explicit over implicit configuration
✓ Visible side effects in function signatures
✓ Clear cause-effect chains in event handling
When to Apply
Apply When
- • Building shared libraries or APIs
- • Onboarding new team members
- • Debugging is taking too long
- • Documentation keeps getting out of sync
- • Users ask "how does this work?"
Balance With
- • Appropriate abstraction (not everything exposed)
- • User-facing simplicity (internal transparency)
- • Security boundaries (some things should hide)
- • Progressive disclosure for complex systems
Reference: Understanding Graphs
UNDERSTANDING.md
Functional transparency for codebases
The Understanding Graphs paper demonstrates functional transparency applied to codebase navigation. Instead of hiding dependency relationships in tooling, UNDERSTANDING.md files expose them in plain markdown.
Every package declares: what it depends on (and why), what depends on it (and for what), and where to start reading. The structure is the documentation.
Part of the CREATE SOMETHING Pattern Library