Rodin
40 lines
1.9 KiB
Markdown
40 lines
1.9 KiB
Markdown
# Elixir Patterns
|
|
|
|
**Prescriptive.** Follow these when writing Elixir code.
|
|
|
|
A pattern is a reusable solution to a recurring problem. Each one has:
|
|
- **When to use** — the problem it solves
|
|
- **When NOT to use** — where it causes harm
|
|
- **Why** — the reasoning, not just the rule
|
|
- **Source citations** — verified file:line from real codebases
|
|
|
|
These are derived from what mature Elixir codebases *actually do*, not opinions or blog posts.
|
|
|
|
## Structure
|
|
|
|
- `patterns/` — what to do (behaviours, GenServer, error handling, testing, typespecs, etc.)
|
|
- `smells/` — what NOT to do (anti-patterns, common mistakes)
|
|
- `sources/` — reference material from specific projects (Oban, elixir-lang). Study for ideas, don't copy blindly.
|
|
|
|
## How to use
|
|
|
|
### Writing code
|
|
|
|
> Read the relevant pattern files from this repo before writing code. Your implementation must follow the documented patterns — if you deviate, justify why in a comment. Check `smells/` to make sure you're not introducing a known anti-pattern.
|
|
|
|
### Reviewing code
|
|
|
|
> Read the relevant pattern files from this repo. For each function or module in the diff, verify it follows the documented pattern. If the code deviates, flag it with a reference to the specific pattern and section. A deviation without justification is a finding.
|
|
|
|
### Evaluating a pattern
|
|
|
|
> Read the pattern file. Compare against how the following projects handle the same problem: [list projects]. Does the pattern hold? Are there cases where it breaks down? Update the pattern with what you find.
|
|
|
|
## Patterns vs Conventions
|
|
|
|
**Pattern** = prescriptive. "When you face X, do Y." Language-scoped. Follow these.
|
|
|
|
**Convention** = descriptive. "Project Z does it this way." Context-specific. Study for ideas — applying another project's conventions to yours without understanding their constraints causes harm.
|
|
|
|
The `sources/` directory is convention material absorbed from thin repos. The `patterns/` directory is what you actually follow.
|