English for Elm Developers

Elm’s strict architecture and famously friendly compiler produce a distinct vocabulary — “The Elm Architecture,” “message,” “no runtime exceptions” — that’s worth using precisely, since Elm developers treat these as concrete guarantees, not marketing phrases. This guide covers the English used when discussing Elm code with a team.

Key Vocabulary

The Elm Architecture (TEA) — the pattern of Model, Update, View that every Elm application follows: state lives in one Model, changes flow through Update, and View renders purely from Model. “This component is reaching outside The Elm Architecture to mutate a value directly — everything needs to flow through a Msg and the Update function instead.”

Message (Msg) — a value describing something that happened (a button click, a server response), the only way state changes are triggered in Elm; there’s no direct mutation. “Instead of updating the model inline inside the view function — which Elm won’t even let you do — dispatch a Msg and handle the state change in Update.”

No runtime exceptions — Elm’s compiler guarantee that a compiling program cannot crash with a null reference, undefined function, or type mismatch at runtime. “We don’t need defensive null checks scattered through this view — Elm’s compiler already guarantees this value can’t be missing, or it wouldn’t have compiled.”

Decoder — a value describing how to parse and validate untyped JSON into a specific typed Elm value, explicitly handling the boundary between untyped external data and Elm’s type system. “This API response isn’t guaranteed to match our assumed shape — write a proper decoder with fallback handling instead of assuming the field will always be present.”

Command (Cmd) — a value describing a side effect (an HTTP request, generating a random number) that Elm’s runtime executes and reports back as a Msg, keeping Update itself pure. “Don’t try to make an HTTP call directly inside Update — return a Cmd describing the request, and let the runtime report the result back as its own Msg.”

Subscription (Sub) — a declaration of external events (WebSocket messages, timers) an Elm application wants to be notified about, delivered as messages just like user interactions. “Add this as a subscription rather than polling manually — the runtime will deliver each WebSocket message as a Msg exactly when it arrives.”

Common Phrases

• “Is this state change flowing through a proper Msg and Update, or is something bypassing the architecture?”
• “Does this decoder handle the case where the field is missing or has an unexpected shape?”
• “Should this side effect be a Cmd, so Update itself stays pure?”
• “Would a subscription be cleaner here than manually polling for this event?”
• “Does the compiler actually guarantee this value can’t be missing, or are we assuming it based on the API docs?”

Example Sentences

Reviewing a pull request: “This decoder assumes the email field is always present, but the API docs mark it optional — use Json.Decode.maybe here instead of failing the whole decode on one missing field.”

Explaining a design decision: “We modeled the multi-step form as one Msg type with explicit variants per step, so Update stays a single exhaustive pattern match instead of scattered boolean flags.”

Describing an incident: “The unexpected blank screen traced back to a decoder silently failing on an unexpected API shape — since Elm has no runtime exceptions, the whole page just showed the initial model instead of crashing.”

Professional Tips

• Say “no runtime exceptions” precisely when explaining why Elm skips certain defensive checks — it’s a compiler guarantee, not an assumption, and worth stating as such.
• Name “The Elm Architecture” explicitly when a change seems to bypass expected data flow — it signals exactly which convention is being violated.
• Use “decoder” rather than “parser” when discussing JSON boundaries — it’s Elm’s precise term and distinguishes it from general string parsing.
• Distinguish Cmd from Sub clearly — one is a one-off side effect request, the other is an ongoing subscription to external events; conflating them causes design confusion.

Practice Exercise

1. Explain in two sentences why Elm has no runtime exceptions if a program compiles successfully.
2. Write a one-sentence code review comment flagging a decoder that assumes a field is always present.
3. Describe, in your own words, the difference between a Cmd and a Sub.

In Practice: Refining Communication with Non-Native Speakers

For many Elm developers – particularly those transitioning from other languages or those who aren’t native English speakers – a core challenge isn’t just understanding the syntax of Elm itself, but navigating the nuances of professional communication. The elegance of Elm’s design can be undermined by clumsy phrasing, overly technical jargon, or simply failing to articulate intentions clearly. This is especially true when discussing concepts like The Elm Architecture (TEA), message passing, and the compiler’s stringent guarantees – areas ripe for misunderstanding if not approached with precision.

A common scenario arises during code reviews. Let’s say a reviewer notices a function that excessively relies on update rather than using actions to trigger updates. A simple, direct comment like “This update is too nested; consider refactoring to use an action” can be interpreted as criticism without context. Instead, a more helpful phrasing would be: “I noticed this uses multiple update calls. Could we streamline this by introducing a specific action that triggers the state change? It will improve readability and make it easier to reason about the flow of updates.” Notice the focus on why the change is suggested – improving readability, promoting clearer reasoning – rather than just stating an opinion. Similarly, in Slack discussions, avoiding overly technical terms like “immutability” when discussing a bug fix related to data structure changes can improve comprehension for those less deeply familiar with Elm’s core principles. Phrases like “This change prevents accidental mutation of the state” are far more accessible than “The immutable nature of this record ensures…”

Furthermore, crafting effective PR descriptions is crucial. A good description should clearly explain what was changed and, crucially, why. Don’t just list the lines of code added or removed; articulate the problem being solved and how your solution addresses it. For example: “Fixes bug where user preferences weren’t correctly persisted across sessions. Introduced a new PreferencesAction to handle preference updates and ensures they are serialized with the application state.” This level of detail reduces ambiguity and allows reviewers to quickly grasp the purpose of the change, even if they aren’t intimately familiar with the specific area of the codebase.

The goal isn’t necessarily to dumb down your communication, but rather to tailor it to your audience. Recognizing that others may have different levels of familiarity with Elm concepts – and specifically, English vocabulary – allows you to craft messages that are both precise and easily understood.

elm reactor --inspect