usage-rules-elixir
Elixir Core Usage Rules
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.
| name | usage-rules-elixir |
|---|---|
| description | Elixir 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/elseorcasein function bodies %{}matches ANY map, not just empty maps. Usemap_size(map) == 0guard 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
withfor chaining operations that return{:ok, _}or{:error, _}
Common Mistakes to Avoid
- Elixir has no
returnstatement, nor early returns. The last expression in a block is always returned. - Don't use
Enumfunctions on large collections whenStreamis more appropriate - Avoid nested
casestatements - refactor to a singlecase,withor separate functions - Don't use
String.to_atom/1on user input (memory leak risk) - Lists and enumerables cannot be indexed with brackets. Use pattern matching or
Enumfunctions - Prefer
Enumfunctions likeEnum.reduceover 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/2notcalc/2 - Predicate function names should not start with
isand should end in a question mark. - Names like
is_thingshould 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]notlist ++ [new]
Mix Tasks
- Use
mix helpto list available mix tasks - Use
mix help task_nameto 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.exsand a specific test with the line numbermix test path/to/test.exs:123 - Limit the number of failed tests with
mix test --max-failures n - Use
@tagto tag specific tests, andmix test --only tagto run only those tests - Use
assert_raisefor testing expected exceptions:assert_raise ArgumentError, fn -> invalid_function() end - Use
mix help testto for full documentation on running tests
Debugging
- Use
dbg/1to print values while debugging. This will display the formatted value and other relevant information in the console.