usage-rules-elixir

Elixir Core Usage Rules

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

When & Why to Use This Skill

This Claude skill provides a comprehensive set of Elixir core usage rules and best practices designed to ensure code quality, performance, and maintainability. It focuses on idiomatic Elixir development, covering essential topics such as pattern matching, error handling with result tuples, efficient data structure usage, and testing standards. By following these guidelines, developers can avoid common pitfalls like memory leaks from dynamic atoms and unidiomatic process dictionary usage.

Use Cases

  • Automated Code Review: Use these rules as a benchmark to evaluate Elixir codebases, ensuring developers prefer pattern matching over conditional logic and use proper guard clauses.
  • Refactoring Legacy Code: Identify and refactor non-idiomatic Elixir code, such as replacing nested case statements with 'with' pipelines or converting Enum operations to Streams for large datasets.
  • Standardizing Error Handling: Implement a consistent error handling strategy across projects by enforcing the use of {:ok, result} and {:error, reason} tuples instead of exceptions for control flow.
  • Performance Optimization: Prevent common performance bottlenecks by following rules on list prepending versus appending and choosing the correct data structures (structs vs. maps) for specific use cases.
  • Onboarding and Mentorship: Serve as a technical style guide for new Elixir developers to quickly learn the language's nuances, such as the absence of early returns and the proper use of predicate function naming.
nameusage-rules-elixir
descriptionElixir Core Usage Rules

Elixir Core Usage Rules

Pattern Matching

  • Use pattern matching over conditional logic when possible
  • Prefer to match on function heads instead of using if/else or case in function bodies
  • %{} matches ANY map, not just empty maps. Use map_size(map) == 0 guard to check for truly empty maps

Error Handling

  • Use {:ok, result} and {:error, reason} tuples for operations that can fail
  • Avoid raising exceptions for control flow
  • Use with for chaining operations that return {:ok, _} or {:error, _}

Common Mistakes to Avoid

  • Elixir has no return statement, nor early returns. The last expression in a block is always returned.
  • Don't use Enum functions on large collections when Stream is more appropriate
  • Avoid nested case statements - refactor to a single case, with or separate functions
  • Don't use String.to_atom/1 on user input (memory leak risk)
  • Lists and enumerables cannot be indexed with brackets. Use pattern matching or Enum functions
  • Prefer Enum functions like Enum.reduce over recursion
  • When recursion is necessary, prefer to use pattern matching in function heads for base case detection
  • Using the process dictionary is typically a sign of unidiomatic code
  • Only use macros if explicitly requested
  • There are many useful standard library functions, prefer to use them where possible

Function Design

  • Use guard clauses: when is_binary(name) and byte_size(name) > 0
  • Prefer multiple function clauses over complex conditional logic
  • Name functions descriptively: calculate_total_price/2 not calc/2
  • Predicate function names should not start with is and should end in a question mark.
  • Names like is_thing should be reserved for guards

Data Structures

  • Use structs over maps when the shape is known: defstruct [:name, :age]
  • Prefer keyword lists for options: [timeout: 5000, retries: 3]
  • Use maps for dynamic key-value data
  • Prefer to prepend to lists [new | list] not list ++ [new]

Mix Tasks

  • Use mix help to list available mix tasks
  • Use mix help task_name to get docs for an individual task
  • Read the docs and options fully before using tasks

Testing

  • Run tests in a specific file with mix test test/my_test.exs and a specific test with the line number mix test path/to/test.exs:123
  • Limit the number of failed tests with mix test --max-failures n
  • Use @tag to tag specific tests, and mix test --only tag to run only those tests
  • Use assert_raise for testing expected exceptions: assert_raise ArgumentError, fn -> invalid_function() end
  • Use mix help test to for full documentation on running tests

Debugging

  • Use dbg/1 to print values while debugging. This will display the formatted value and other relevant information in the console.