English for Crystal Language Developers

Crystal reads like Ruby but compiles like a systems language, and that combination creates a specific vocabulary gap: developers coming from Ruby have the syntax vocabulary already, but not the compile-time and concurrency vocabulary Crystal actually requires to discuss its behavior precisely.

Key Vocabulary

Type inference (compile-time) — Crystal’s process of determining every variable’s type at compile time without explicit annotations in most cases, which is why Crystal code looks untyped like Ruby but behaves like a statically typed compiled language. “You don’t need to annotate that return type — type inference already resolves it at compile time from the two branches, and the compiler will reject the build if they don’t unify into one consistent type.”

Union type — a type representing “one of several possible types,” which Crystal’s compiler tracks precisely so that every downstream operation is verified against all members of the union, not just the common case. “This variable ends up with a union type of String | Nil because of that early return — the compiler’s forcing you to handle the nil case explicitly before you can call a string method on it.”

Macro (compile-time) — Crystal code that runs during compilation to generate other code, distinct from a runtime function call, used for eliminating boilerplate without paying any runtime cost. “We’re using a macro to generate the getter and setter methods for all twelve fields at compile time, instead of hand-writing them or reflecting on the object at runtime the way Ruby would.”

Fiber — Crystal’s lightweight, cooperatively scheduled unit of concurrency, similar to a goroutine, that lets thousands of concurrent tasks run without the overhead of OS threads. “Don’t spawn an OS thread for each incoming connection — spawn a fiber instead. Crystal’s scheduler multiplexes thousands of fibers onto a small number of OS threads for you.”

Shard — Crystal’s term for a package/dependency, managed via shard.yml and the shards command, analogous to a Ruby gem but resolved and compiled statically into the final binary. “Pin that shard to an exact version in shard.yml — since Crystal compiles dependencies directly into the binary, an unpinned shard update can change runtime behavior on your next build, not just your next bundle install.”

Common Phrases

• “Does type inference resolve that at compile time, or do we need an explicit annotation here?”
• “Is this a union type we need to narrow, or does the compiler already know it’s just one type?”
• “Is that a compile-time macro, or a regular runtime method call?”
• “Should this spawn a fiber, or does it actually need a real OS thread?”
• “Is that shard pinned to an exact version in shard.yml?”

Example Sentences

Explaining a compiler error to a teammate: “The compiler’s complaining because this ends up with a union type of Int32 | String, and you’re calling a method that only exists on Int32. You need to narrow the union with a type check before calling it.”

Describing a performance choice: “We’re using macros to generate the serialization methods at compile time instead of using runtime reflection — Crystal doesn’t do runtime reflection the way Ruby does, so this is genuinely the idiomatic approach here, not just an optimization.”

Explaining a concurrency design: “Each incoming request spawns its own fiber, and Crystal’s scheduler handles multiplexing them onto a handful of OS threads — that’s why we can handle tens of thousands of concurrent connections without the memory overhead of one thread per connection.”

Professional Tips

• Let type inference do the work in most cases, and only add explicit type annotations at public method boundaries, where they double as documentation for callers — over-annotating internal code just adds noise.
• Treat a union type the compiler reports as useful information, not an obstacle — narrow it explicitly with a type check or case rather than reaching for an unsafe cast to silence the compiler.
• Reach for a compile-time macro only when you’re eliminating genuine boilerplate across many similar definitions — macros are harder to debug than plain methods, so the payoff needs to be real.
• Default to spawning a fiber for concurrent work rather than an OS thread — fibers are Crystal’s idiomatic concurrency primitive, and mixing in real threads should be a deliberate, justified exception.
• Always pin a shard to an exact version for anything shipping to production, since Crystal statically compiles dependencies into the binary — an unpinned version means your next build can silently change behavior.

Practice Exercise

1. Explain the difference between compile-time type inference and a runtime type check.
2. Describe when you’d reach for a compile-time macro instead of a regular method.
3. Write a sentence explaining why fibers are preferred over OS threads for concurrent I/O in Crystal.

Navigating Feedback Loops – A Practical Approach

Crystal’s strengths – compile-time safety, rapid iteration via macros, and efficient concurrency – often lead to exciting results. However, those same features can introduce nuances in communication when discussing code with others. When working collaboratively, especially across teams or with varying levels of experience, it’s crucial to frame feedback effectively, not just state what you see as a problem. The goal isn’t necessarily to be critical, but to ensure shared understanding and drive improvements. Think about how you might explain the benefits of type inference to someone unfamiliar with Crystal – highlighting its ability to catch errors early prevents wasted effort later. Similarly, when discussing complex macro usage, clarity is paramount. Avoid jargon that might alienate a reviewer; instead, focus on the intent behind the macro and its impact on the codebase.

A common pitfall for developers transitioning from dynamically-typed languages like Ruby is assuming everyone understands the implications of compile-time decisions. A simple comment like “This doesn’t type correctly” will likely be met with confusion. Instead, try phrasing it as, “I’m concerned that this function doesn’t explicitly declare its return type, which could potentially lead to runtime errors if the implementation changes slightly. Adding a returns: String annotation might improve clarity and help prevent unexpected behavior.” Similarly, when discussing shard dependencies, avoid overly technical descriptions. Frame it in terms of business impact – “This change improves data locality for users in Europe, reducing latency and improving response times.”

Effective communication also extends to describing changes concisely. Use clear action verbs and focus on the what and why, rather than dwelling on the how. For example, instead of saying “I refactored this code,” try “I improved the readability of this function by extracting it into a separate module.” This approach is especially important when documenting pull requests – aim for descriptions that provide sufficient context without overwhelming the reviewer.

Here’s an example using crystal new to create a simple program with some basic type inference:

# hello.cr
def greet(name)
  "Hello, #{name}!"
end

puts greet("World")

This demonstrates how Crystal’s type inference allows for concise and expressive code while still providing compile-time guarantees. When discussing this with a less experienced developer, you might highlight the lack of explicit type declarations – emphasizing that the compiler has inferred the String type automatically based on the string literal. This is a key concept to explain clearly when introducing others to Crystal’s approach.