Elixir Best Practices

Analogy categoryAnalogies

Writing Idiomatic, Maintainable Elixir

Idiomatic Elixir favors small, single-purpose functions composed with the pipe operator (|>) over large monolithic functions, snake_case naming for functions and variables, a trailing question mark for functions returning booleans (e.g. Enum.empty?/1), and a trailing bang for functions that raise on failure instead of returning an error tuple (e.g. File.read!/1 versus File.read/1). Following these naming conventions isn't just cosmetic -- they're a contract that lets any Elixir developer predict a function's behavior from its name alone, without reading its implementation first.

🏏

Cricket analogy: Just as a scorecard consistently marks a not-out batsman with an asterisk so any fan instantly understands the state without reading commentary, Elixir's trailing ? on Enum.empty?/1 tells any developer at a glance that the function returns a boolean.

Pattern Matching Over Conditional Logic

Instead of writing one function body full of if/case/cond branches, idiomatic Elixir defines multiple function clauses, each matching a specific shape of the input via pattern matching and guard clauses, letting the BEAM's clause-matching do the branching for you. For example, a discount/2 function might have one clause matching %{type: :vip} and another matching any other struct, rather than a single clause with an if user.type == :vip. This style keeps each clause short, makes it trivial to add a new case without touching existing logic, and turns exhaustiveness (did I forget a case?) into something the compiler can help flag via Dialyzer rather than something buried in nested conditionals.

🏏

Cricket analogy: It's like a bowling attack with a dedicated bowler for each specific situation -- a yorker specialist for the death overs, a spinner for the middle overs -- rather than one all-purpose bowler trying to handle every situation with a single adjustable plan.

Structuring Processes and Supervision

Elixir's process model is powerful, but idiomatic code doesn't reach for a GenServer every time state needs to be held -- plain functions and immutable data are the default, and a process is introduced specifically when you need concurrent access, isolated state that outlives a single request, or a well-defined restart boundary. When a process is genuinely warranted, it should be started under a Supervisor with a restart strategy chosen deliberately: :one_for_one restarts only the crashed child, while :rest_for_one or :one_for_all restart siblings too when they have interdependent state, so choosing the wrong strategy either under-recovers (dependent processes left in a stale state) or over-recovers (unnecessarily restarting healthy processes).

🏏

Cricket analogy: Choosing :one_for_one is like a captain substituting only the injured fielder while the rest of the team keeps playing; choosing :one_for_all is like calling for an entire team timeout because one player needed treatment, even though it wasn't necessary.

Error Handling: Bang Functions, Tagged Tuples, and with

The dominant Elixir convention for fallible operations is to return a tagged tuple, {:ok, result} on success or {:error, reason} on failure, rather than raising exceptions for expected failure paths; exceptions and their ! counterparts are reserved for truly exceptional, programmer-error situations. When a sequence of operations can each fail independently, Elixir's with special form lets you chain them cleanly, matching each step's success pattern and short-circuiting to a single else clause on the first mismatch, which replaces what would otherwise be a pyramid of nested case statements.

🏏

Cricket analogy: It's like an umpire signaling a clear, standardized decision -- out or not out -- rather than stopping play with a dramatic incident every time; with is like a chain of umpiring checks (no-ball, LBW, review) that stops cleanly at the first failed check.

elixir

defmodule Discount do
  @spec apply(map()) :: {:ok, float()} | {:error, atom()}
  def apply(%{type: :vip, total: total}) when total > 0 do
    {:ok, total * 0.8}
  end

  def apply(%{type: :regular, total: total}) when total > 0 do
    {:ok, total * 0.95}
  end

  def apply(%{total: total}) when total <= 0 do
    {:error, :invalid_total}
  end
end

with {:ok, user} <- Accounts.fetch_user(id),
     {:ok, cart} <- Cart.fetch(user),
     {:ok, price} <- Discount.apply(cart) do
  {:ok, price}
else
  {:error, reason} -> {:error, reason}
end

Run mix format on every save (most editors wire this to a pre-commit hook) and add mix credo --strict to CI -- Credo's static analysis catches idiomatic-style issues like deeply nested code, unused aliases, and overly complex functions before they reach code review.

Not everything needs to be a GenServer. Reaching for a process purely to hold configuration or memoize a pure computation adds message-passing overhead and a new failure mode for no real benefit -- a plain module with functions (or an ETS table for shared read-heavy caching) is often the simpler, faster, and more idiomatic choice.

Documentation, Typespecs, and Testing Discipline

Idiomatic Elixir modules document their public contract with @moduledoc and @doc (which double as the source for generated documentation and doctests), and specify function signatures with @spec so tools like Dialyzer can statically catch type mismatches that would otherwise only surface at runtime. Testing discipline in Elixir typically combines ExUnit unit tests, doctests extracted directly from @doc examples (so documentation and tests can never silently drift apart), and for logic with many edge cases, property-based testing via the StreamData library, which generates hundreds of randomized inputs to find edge cases a handful of hand-written examples would miss.

🏏

Cricket analogy: It's like a player's official stats sheet (average, strike rate) that's automatically verified against every match scorecard, so the published record can never silently drift from what actually happened on the field -- that's what doctests do for documentation.

Follow Elixir's naming conventions: snake_case, ? suffix for boolean-returning functions, ! suffix for functions that raise instead of returning an error tuple.
Prefer multiple pattern-matched function clauses and guards over large if/case/cond chains for clearer, more extensible branching logic.
Introduce a GenServer or process only when you genuinely need concurrent access, long-lived state, or an isolated restart boundary -- not as a default for holding state.
Choose Supervisor restart strategies (:one_for_one, :one_for_all, :rest_for_one) deliberately based on whether sibling processes share interdependent state.
Return {:ok, result} / {:error, reason} tuples for expected failure paths, and reserve exceptions/! functions for truly exceptional cases.
Use with to chain multiple fallible operations cleanly, avoiding deeply nested case pyramids.
Pair @doc/@moduledoc and @spec with ExUnit doctests, and use StreamData property-based tests for logic with many edge cases.