# Simplicity The bar code in plushie-elixir has to clear, and the recurring tradeoffs about structure and abstraction that decide what earns its place. The other stewardship docs (`performance-bar.md`, `resilience.md`, `test-discipline.md`, `dsl-discipline.md`) each carry a flavor of this implicitly; this doc states it directly so questions about "should we extract this" or "is this clear enough" have an explicit reference. This is not a style guide. Naming, formatting, lint rules, and language-specific idioms live in `mix format`, Credo, and the project's `.formatter.exs`. This doc is about the posture above those: when to add complexity, when to refuse it, what clarity costs, and what readability buys. ## Clarity is a constraint, not an aspiration Code in plushie-elixir has to read clearly to an Elixir engineer who has not been in this codebase before. "It works" is the floor; "it can be understood without context" is the bar. Every reader pays the cost of obscure code. The author writes it once; many readers will read it. Small clarity wins compound across hundreds of files; small obscurity losses compound the other way. Same compounding argument that drives the lightweight- by-default stance in `performance-bar.md`, applied to reader cost instead of CPU cost. The bar is not negotiable. Optimizations, abstractions, defensive layers, refactors, and macro additions all have to clear it; the readability test wins ties. ## Abstraction has to earn its place Extracting a helper, a module, a behaviour, a macro, a protocol: each carries cost. A reader has to follow the indirection, hold the abstraction's contract in their head, and decide whether what the call site shows reflects what the abstraction does inside. The benefit has to clearly outweigh that cost. Working rules: - **Three similar lines is better than a premature abstraction.** Two pieces of code that look similar today might diverge tomorrow; extracting them now locks them together for reasons that may not survive contact with future requirements. - **By the third use of a similar pattern, the abstraction earns consideration.** Not commitment, consideration. The question is whether the three uses are the same concept or three coincidentally similar ones. - **An abstraction with one user is a costume, not an abstraction.** Single-use indirection is overhead. A protocol with one impl, a behaviour with one module, a macro that wraps one call site. - **"We might need this someday" is a reason not to extract.** Generic code written for hypothetical future users is the recurring source of half-built abstractions that nobody fully understands later. The DSL is especially vulnerable here; see `dsl-discipline.md`. - **Generic where specific would do is harder to read.** A concrete struct beats a parameterized one when the parameterization does not have at least two real uses. These are working positions, not absolute rules. The burden is on the proposed abstraction to push against them. ## Local complexity over global complexity A 200-line function that does one thing clearly is preferable to the same logic spread across five files in pursuit of "smaller functions." Locality is a feature: a reader can hold the whole thing in view. Following control flow across ten indirections costs more than reading a longer linear sequence. Module size on its own is not a problem. A large module is not an invitation to split unless a real change is forced to bend around its existing shape. Refactoring without a forcing function is a non-goal (`goals-and-non-goals.md`); this is one of the places that rule shows up most often. The runtime is large because the runtime does a lot; that is fine. Files split for the sake of "smaller files" frequently end up with cross-file dependencies that obscure the same logic the single file made obvious. Cohesion across a file beats brevity of any one file. ## Functional flavor The codebase is functional-first; Elixir's natural fit. The Elm-architecture pattern (`init/update/view`) is the SDK's structural backbone for a reason. The recurring choices that follow: - **Pure functions where possible.** Side effects push to the edges (Bridge owns I/O, command execution wraps effectful calls, the rest of the runtime is functional). `update/2` is pure: it returns a new model and commands; the runtime performs the commands. - **Immutable data.** Elixir is immutable by default, and the codebase keeps it that way. ETS, agents, and process state are used where they belong, not as ergonomics for "just mutate this." - **Pattern matching over branching.** Multi-clause function heads, destructuring binds, and guards beat nested `if`/`case` chains where the shapes are stable. When the shapes are not stable, a single `case` is clearer than pattern-matched dispatch the reader has to reconstruct. - **Sum types over flag-based state machines.** A union of named structs (`%KeyEvent{}`, `%WidgetEvent{}`, `%WindowEvent{}`, etc.) beats a generic event map with three booleans and an unwritten rule about which combinations are valid. `@enforce_keys` is part of this; it makes invalid shapes unconstructable. - **Errors as values.** `{:ok, value}` / `{:error, reason}` for recoverable conditions; raise for invariant violations only (see `resilience.md`). `with` for chained value-returning steps where the early-exit shape is the point. - **Pipelines where they read top-down.** A pipe that flows through transformations is clearer than nested calls; a pipe that requires the reader to mentally re-thread arguments is not. The threshold is the reader, not the line count. - **Composition over inheritance-shaped patterns.** Behaviours define a contract; modules implement it. Protocols dispatch on type. There is no `extend`, no `super`, no inheritance. Composition through smaller modules with explicit dependencies is the shape that scales. Elixir idiom prevails on syntax (snake_case, atom keys, `{:ok, _}` tuples, `with` blocks, pipelines). The concept- level patterns above converge with the rest of the project ecosystem (see `posture.md` on the cross-SDK story). ## Comments earn their place too Code should explain itself. Comments answer questions the code cannot: - A non-obvious constraint or invariant the surrounding code holds. - A surprising or subtle behavior a reader might trip on. - A workaround for a specific external issue that the reader needs to understand to evaluate the code. Comments are not for explaining what the next line does. If a comment is needed to explain what, the code itself usually wants to be clearer. `@moduledoc` and `@doc` are documentation, not comments; they have a different purpose and a different bar. Public modules and callbacks have docstrings that read as user-facing documentation. Internal modules use `@moduledoc false` rather than empty docstrings. ## Implications - Abstractions added without justifying use are declined, even when technically correct. - Refactors that fragment a coherent module into smaller files without a forcing function are declined. - Half-built abstractions (extracted but only partially applied, or extracted with planned consumers never arriving) are bug-class. Either complete the application or fold the abstraction back into the call sites. - Reviewer comments of the form "I had to re-read this three times" are first-class and earn a rewrite, regardless of whether the code is correct as written. - Typespecs use the verbose `name :: type()` parameter form for clarity; dialyzer suppression for type mismatches is a signal the type is wrong, not a tool for silencing it.