Usage Rules

IMPORTANT: Consult these usage rules early and often when working with the packages listed below. Before attempting to use any of these packages or to discover if you should use them, review their usage rules to understand the correct patterns, conventions, and best practices.

ash_authentication usage

_Authentication extension for the Ash Framework. _

ash_authentication usage rules

ash_phoenix usage

_Utilities for integrating Ash and Phoenix _

ash_phoenix usage rules

ash_postgres usage

_The PostgreSQL data layer for Ash Framework _

ash_postgres usage rules

igniter usage

_A code generation and project patching framework _

igniter usage rules

usage_rules:elixir usage

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

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

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

usage_rules:otp usage

OTP Usage Rules

GenServer Best Practices

Keep state simple and serializable
Handle all expected messages explicitly
Use
```
handle_continue/2
```
for post-init work
Implement proper cleanup in
```
terminate/2
```
when necessary

Process Communication

Use
```
GenServer.call/3
```
for synchronous requests expecting replies
Use
```
GenServer.cast/2
```
for fire-and-forget messages.
When in doubt, us
```
call
```
over
```
cast
```
, to ensure back-pressure
Set appropriate timeouts for
```
call/3
```
operations

Fault Tolerance

Set up processes such that they can handle crashing and being restarted by supervisors
Use
```
:max_restarts
```
and
```
:max_seconds
```
to prevent restart loops

Task and Async

Use
```
Task.Supervisor
```
for better fault tolerance
Handle task failures with
```
Task.yield/2
```
or
```
Task.shutdown/2
```
Set appropriate task timeouts
Use
```
Task.async_stream/3
```
for concurrent enumeration with back-pressure

ash_oban usage

_The extension for integrating Ash resources with Oban. _

ash_oban usage rules

ash usage

_A declarative, extensible framework for building Elixir applications. _

ash usage rules

Common Mistakes to Avoid

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

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

Related Skills

Markdown Converter

Nano Banana Pro

1password