docs: add patterns extracted from elixir-lang/elixir source

Using codebase-analysis skill (patterns mode) on the language source. Real examples from the repo, not invented. Each pattern has: - Rule, Example, Why, When NOT to use, Source file. Topics: module org, protocol design, error handling, testing, documentation, naming, process design, smells.
2026-04-30 13:26:23 -07:00
parent e51f491b6e
commit e6fbfced96
1 changed files with 326 additions and 0 deletions
@@ -0,0 +1,326 @@
+# Elixir Patterns (from Source)
+
+Prescriptive patterns extracted from elixir-lang/elixir source.
+"If writing new Elixir, follow these rules."
+
+---
+
+## Module Organization
+
+### One Module Per Concept
+
+**Rule:** Each module owns exactly one concept. If you can't name it in
+2-3 words, it's too broad.
+
+```elixir
+# Source: lib/elixir/lib/string.ex — String is strings. Period.
+defmodule String do
+  @moduledoc """
+  Strings in Elixir are UTF-8 encoded binaries.
+  """
+  @type t :: binary
+```
+
+**Why:** The Elixir source has zero "util" or "helper" modules. Every
+module has a noun name that IS the thing.
+
+**When NOT to use:** Kernel is the exception — it's the implicit
+surface area. You don't get to make your own Kernel.
+
+**Source:** Every file in `lib/elixir/lib/` follows this.
+
+### @moduledoc false for Internal Modules
+
+**Rule:** Internal modules that users shouldn't call get `@moduledoc false`.
+
+```elixir
+# Source: lib/elixir/lib/code/formatter.ex
+defmodule Code.Formatter do
+  @moduledoc false
+```
+
+**Why:** Hides from docs. Signals "this is implementation, not API."
+The Elixir team uses this for 30+ internal modules.
+
+**When NOT to use:** If ANYONE outside your team might call it. Public
+API must have docs.
+
+---
+
+## Protocol Design
+
+### Protocols for External Extension
+
+**Rule:** Define a protocol when users need to extend behavior for
+their own types.
+
+```elixir
+# Source: lib/elixir/lib/collectable.ex
+defprotocol Collectable do
+  @doc """
+  Returns an initial accumulation value and a "collector" function.
+  """
+  @spec into(t) :: {initial_acc :: term, collector(term)}
+  def into(collectable)
+end
+```
+
+**Why:** Protocols dispatch on the first argument's type. They're the
+extension point for "I made a new data structure and want it to work
+with Enum."
+
+**When NOT to use:** When you control all implementations. Use
+behaviours instead. Protocols are for open extension; behaviours are
+for closed contracts.
+
+### Only 6 Stdlib Protocols
+
+**Rule:** Be conservative defining protocols. The Elixir stdlib has
+only 6 in 15 years.
+
+- `Enumerable` — iterate over things
+- `Collectable` — put things into containers
+- `Inspect` — debug representation
+- `String.Chars` — convert to string
+- `List.Chars` — convert to charlist
+- `JSON.Encoder` — JSON serialization (added 2024)
+
+**Why:** Each protocol is a permanent API commitment. Once defined,
+every type in the ecosystem may implement it.
+
+**When NOT to use:** Don't define a protocol for something only your
+app needs. A behaviour or function argument is cheaper.
+
+---
+
+## Error Handling
+
+### Tagged Tuples for Expected Failures
+
+**Rule:** Return `{:ok, value}` or `{:error, reason}` for operations
+that can fail in expected ways.
+
+```elixir
+# Source: lib/elixir/lib/file.ex
+@spec read(Path.t()) :: {:ok, binary} | {:error, posix}
+def read(path) do
+  case :file.read_file(path) do
+    {:ok, binary} -> {:ok, binary}
+    {:error, reason} -> {:error, reason}
+  end
+end
+```
+
+**Why:** Pattern matching makes handling explicit. The caller MUST
+decide what to do with errors — they can't accidentally ignore them.
+
+**When NOT to use:** For programmer errors (bugs). Those should raise.
+`File.read!` raises; `File.read` returns tuples.
+
+### Bang Functions for "Should Never Fail"
+
+**Rule:** Provide `function!` variant that raises on error. Use when
+failure means a bug in the caller.
+
+```elixir
+# Convention: function returns {:ok, _} | {:error, _}
+#             function! raises on error
+File.read("path")   # => {:ok, "..."} | {:error, :enoent}
+File.read!("path")  # => "..." | raises File.Error
+```
+
+**Why:** The `!` signals to the reader: "I expect this to succeed. If
+it doesn't, crash." This is intentional — crashing is the correct
+response to unexpected errors in OTP.
+
+**When NOT to use:** When failure is expected and the caller should
+handle it (use tagged tuples).
+
+---
+
+## Testing
+
+### CaseTemplate for Shared Setup
+
+**Rule:** Use `ExUnit.CaseTemplate` when multiple test files share
+setup logic.
+
+```elixir
+# Source: lib/ex_unit/lib/ex_unit/case_template.ex
+defmodule MyApp.DataCase do
+  use ExUnit.CaseTemplate
+
+  setup tags do
+    :ok = Ecto.Adapters.SQL.Sandbox.checkout(MyApp.Repo)
+    unless tags[:async] do
+      Ecto.Adapters.SQL.Sandbox.mode(MyApp.Repo, {:shared, self()})
+    end
+    :ok
+  end
+end
+```
+
+**Why:** Inheritance via `use` is how Phoenix's ConnCase/DataCase work.
+This pattern comes directly from ExUnit itself.
+
+**When NOT to use:** For helpers that don't need lifecycle callbacks.
+Simple `import` is cleaner for utility functions.
+
+### async: true by Default
+
+**Rule:** Mark tests `async: true` unless they touch shared state.
+
+**Why:** Async tests run in parallel. The Elixir stdlib tests show that
+most tests CAN be async — only database/file/process tests need
+serialization.
+
+**When NOT to use:** Tests that modify global state, shared files, or
+named processes.
+
+---
+
+## Documentation
+
+### Every Public Function Gets @doc + @spec
+
+**Rule:** All public functions have both `@doc` and `@spec`.
+
+```elixir
+# Source: lib/elixir/lib/enum.ex
+@doc """
+Returns `true` if all elements in `enumerable` are truthy.
+"""
+@spec all?(t) :: boolean
+def all?(enumerable) when is_list(enumerable) do
+```
+
+**Why:** Specs enable Dialyzer checking. Docs generate ExDoc pages. The
+Elixir stdlib has zero undocumented public functions.
+
+**When NOT to use:** `@moduledoc false` modules skip docs (they're
+internal).
+
+### @type t for Structs
+
+**Rule:** Every struct defines `@type t` with field types.
+
+```elixir
+# Source: lib/elixir/lib/kernel.ex (defstruct docs)
+defmodule User do
+  defstruct name: "John", age: 25
+  @type t :: %__MODULE__{name: String.t(), age: non_neg_integer}
+end
+```
+
+**Why:** Enables Dialyzer to catch type mismatches at struct boundaries.
+Without `@type t`, struct fields are effectively untyped.
+
+---
+
+## Naming
+
+### Modules Are Nouns
+
+**Rule:** Module names are nouns. Never verbs, never adjectives.
+
+`String`, `Enum`, `Map`, `File`, `Logger`, `GenServer`
+
+**Why:** A module IS a thing. Functions are what you DO with that thing.
+`String.split/2` reads as "take a String, split it."
+
+**When NOT to use:** Mix tasks (they're commands: `Mix.Tasks.Deps.Get`).
+
+### Functions Are Verbs
+
+**Rule:** Function names start with a verb (or are a question with `?`).
+
+`Enum.map/2`, `String.split/2`, `File.read/1`, `Enum.empty?/1`
+
+**Why:** `module.verb(subject)` reads as a sentence.
+
+### Underscore Prefix for Unused
+
+**Rule:** Prefix unused variables with `_`.
+
+```elixir
+def handle_info(_message, state), do: {:noreply, state}
+```
+
+**Why:** Compiler warning suppression AND documentation that the value
+is intentionally ignored.
+
+---
+
+## Process Design
+
+### GenServer for Stateful Services
+
+**Rule:** Use GenServer when you need mutable state that outlives a
+request.
+
+```elixir
+# Source: lib/iex/lib/iex/broker.ex
+defmodule IEx.Broker do
+  use GenServer
+  # ...
+end
+```
+
+**Why:** GenServer gives you: message serialization, supervision tree
+integration, hot code upgrade, `:sys` debugging.
+
+**When NOT to use:** Stateless transformations (just use functions).
+One-off concurrent work (use Task). Accumulating state within a request
+(use recursion or reduce).
+
+### Agent for Simple State
+
+**Rule:** Use Agent when you only need get/update on a value — no
+complex message handling.
+
+```elixir
+# Source: lib/mix/lib/mix/tasks_server.ex
+defmodule Mix.TasksServer do
+  use Agent
+end
+```
+
+**Why:** Agent is GenServer with the common case optimized. Less
+boilerplate for "I just need a mutable box."
+
+**When NOT to use:** When you need `handle_info`, timeouts, or multiple
+operations that must be atomic.
+
+---
+
+## Smells
+
+### GenEvent (Deprecated Pattern)
+
+```elixir
+# Source: lib/elixir/lib/gen_event.ex
+@moduledoc deprecated: "Use one of the alternatives described below"
+```
+
+The Elixir team deprecated their own GenEvent. Alternatives: Registry +
+GenServer, or Phoenix.PubSub. Lesson: event buses that try to do
+everything are worse than composed primitives.
+
+### Version-Gated TODOs (Deferred Cleanup)
+
+```elixir
+# TODO: Remove me on v2.0
+# TODO: Deprecate me on Elixir v1.23
+```
+
+127 of these exist. They're not smells in the "bad code" sense — 
+they're discipline. But if YOUR code has TODOs without version targets,
+that IS a smell.
+
+### @moduledoc false Proliferation
+
+30+ internal modules in the stdlib. If your app has this many, you may
+be over-splitting. Internal modules should be rare in application code
+— they're appropriate for libraries and frameworks.
+
+<!-- PATTERN_COMPLETE -->