English for Gleam Developers

Gleam brings a statically-typed, functional language to the BEAM (the Erlang virtual machine), which means its vocabulary blends Erlang/Elixir concurrency terms with type-system vocabulary from languages like Rust and OCaml. A team needs to be precise about which layer a bug or design question belongs to — the type system, or the runtime’s process model. This guide covers the English used when discussing Gleam code with a team.

Key Vocabulary

Exhaustiveness checking — the compiler’s guarantee that a case expression handles every possible variant of a custom type, catching missing branches at compile time rather than at runtime. “The compiler is refusing to build because this case doesn’t handle the new Cancelled variant — that’s exhaustiveness checking doing exactly its job.”

Custom type — Gleam’s tagged union type (similar to an enum with data), used to model a fixed set of distinct states or variants explicitly, rather than relying on strings or booleans. “Instead of a boolean is_error flag plus a nullable message field, model this as a custom type with Ok and Error variants — it makes invalid states unrepresentable.”

BEAM process — a lightweight, isolated unit of concurrency provided by the Erlang VM, which Gleam code runs on and can spawn cheaply, each with its own memory and message mailbox. “Don’t share mutable state between these two BEAM processes directly — send a message instead, that’s the concurrency model the whole platform is built around.”

Result type — Gleam’s built-in Result(a, b) type representing either success (Ok) or failure (Error), used pervasively instead of exceptions for expected failure cases. “This function returns a Result instead of throwing, so the caller is forced by the type system to explicitly handle the error case — nothing can silently ignore it.”

Let assert — a pattern-matching construct that asserts a value matches a specific shape, crashing at runtime if it doesn’t, used deliberately for cases considered truly unreachable. “Using let assert Ok(value) = result here is fine because we’ve already validated this can’t fail — but flag it in review, since it bypasses the exhaustiveness guarantee.”

Supervision tree — an Erlang/Elixir/Gleam pattern where processes are organized hierarchically, with supervisors automatically restarting failed child processes according to a defined strategy. “If this worker crashes on a bad message, the supervision tree just restarts it cleanly — we don’t need defensive error handling everywhere, the platform handles recovery.”

Common Phrases

• “Does this case expression handle every variant, or is the compiler flagging a missing branch?”
• “Should this be a custom type instead of a raw string or boolean flag?”
• “Is this state shared between processes, or passed via a message?”
• “Is this function returning a Result, or does failure need to be handled another way?”
• “Is this let assert actually safe, or could that input realistically fail?”

Example Sentences

Reviewing a pull request: “This uses a plain string to represent the order status — let’s model it as a custom type with explicit variants so the compiler catches any unhandled case at build time.”

Explaining a design decision: “We split this into two BEAM processes, one for the incoming message queue and one for processing, so a slow processor doesn’t block message intake.”

Describing a bug: “The crash happened because a let assert on a value we assumed was always present actually failed under a rare input — we should have used a proper case with an explicit error path.”

Professional Tips

• Say “exhaustiveness checking” specifically when explaining why the compiler rejects an incomplete case — it’s the feature’s actual name, not just “type checking.”
• When reviewing state representation, ask “could this be a custom type instead?” — this is the standard nudge away from stringly-typed or boolean-flag designs in Gleam code review.
• Use “BEAM process” rather than “thread” — they are a different concurrency primitive with different guarantees, and conflating the terms confuses newcomers from other languages.
• Flag “let assert” explicitly in review as a deliberate escape hatch from exhaustiveness — it should be rare and justified, not a default habit.

Practice Exercise

1. Explain in two sentences why exhaustiveness checking catches bugs that a runtime language wouldn’t.
2. Write a one-sentence code review comment recommending a custom type over a boolean flag.
3. Describe, in your own words, why sharing mutable state between BEAM processes goes against the platform’s design.

Mastering Communication in the Gleam Ecosystem

Gleam’s power lies in its blend of functional programming concepts with Erlang’s BEAM runtime – offering a unique approach to building robust, type-safe applications. However, effective communication within a development team relies heavily on precise English and understanding terminology related to pattern matching, exhaustiveness checking, and the underlying technology. This section focuses on equipping you with the vocabulary needed for productive discussions when working with Gleam developers.

One of the key challenges when transitioning from other languages is grasping the nuances of exhaustive pattern matching. It’s not simply about finding a match; it’s about ensuring every possible case within a data structure has been explicitly accounted for. This concept directly relates to the BEAM runtime’s focus on efficiency and resource management – an exhaustive match minimizes unnecessary computations. You’ll frequently hear terms like “covering all branches,” “complete pattern matching,” or “exhaustive search.” Don’t just look for a solution; ensure you’ve considered all possible solutions.

Another crucial area is discussing code reviews, where the focus shifts from simply working in isolation to collaborating and receiving feedback. You’ll encounter phrases like “reduce cognitive load” (referring to making the code easier to understand), “improve readability,” or “eliminate ambiguity.” When pointing out a potential issue, frame it constructively: “This pattern could be made more explicit to ensure exhaustive coverage” instead of simply saying “There’s an error here.” The goal is always to improve the clarity and maintainability of the code.

Finally, understanding the relationship between Gleam’s type system and Erlang’s BEAM runtime is paramount. You will frequently discuss concepts like “compile-time checking,” “runtime guarantees,” and “static analysis.” The type system provides a layer of safety by enforcing constraints at compile time, which in turn enables the BEAM runtime to optimize execution further.

Here’s a simple example demonstrating how this vocabulary might be used during a code review:

def process_data(data):
    match {
        [] -> Ok(None)  // Empty list – success
        [x] -> Ok(x)   // Single element – success
        [x, y, z] -> Err("Too many elements") // Three elements - error
        _ -> Err("Unexpected pattern") // Catch-all – error
    }

In this example, the match statement demonstrates exhaustive pattern matching. The comments highlight the discussion points: “ensure complete coverage,” “reduce ambiguity” about the expected data structure and its potential errors. The use of Ok and Err aligns with common Erlang/BEAM error handling patterns.