usage-rules-elixir
Elixir Core Usage Rules
When & Why to Use This Skill
This Claude skill provides a comprehensive framework for Elixir development, enforcing idiomatic coding standards and core usage rules. It optimizes Elixir codebases by promoting pattern matching, functional design, and efficient data structure usage while preventing common pitfalls like memory leaks and unidiomatic recursion.
Use Cases
- Automated Code Review: Use these rules to audit Elixir pull requests, ensuring the code follows best practices for pattern matching, guard clauses, and error handling.
- Refactoring Legacy Code: Guide the refactoring of complex conditional logic into clean, multi-clause functions and 'with' statements for better readability.
- Performance Tuning: Identify and replace eager Enum operations on large datasets with lazy-evaluated Streams to optimize memory usage.
- Standardizing Project Architecture: Establish a consistent foundation for new Elixir projects by enforcing standardized naming conventions and testing methodologies using Mix tasks.
| 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.