79 lines
1.9 KiB
Markdown
79 lines
1.9 KiB
Markdown
# Code-related anti-patterns
|
|
|
|
This document outlines anti-patterns related to your code and particular Elixir idioms and features.
|
|
|
|
## Comments
|
|
|
|
#### Problem
|
|
|
|
When you overuse comments or comment self-explanatory code, it can have the effect of making code *less readable*.
|
|
|
|
#### Example
|
|
|
|
```elixir
|
|
# Returns the Unix timestamp of 5 minutes from the current time
|
|
defp unix_five_min_from_now do
|
|
# Get the current time
|
|
now = DateTime.utc_now()
|
|
|
|
# Convert it to a Unix timestamp
|
|
unix_now = DateTime.to_unix(now, :second)
|
|
|
|
# Add five minutes in seconds
|
|
unix_now + (60 * 5)
|
|
end
|
|
```
|
|
|
|
#### Refactoring
|
|
|
|
Prefer clear and self-explanatory function names, module names, and variable names when possible. In the example above, the function name explains well what the function does, so you likely won't need the comment before it. The code also explains the operations well through variable names and clear function calls.
|
|
|
|
You could refactor the code above like this:
|
|
|
|
```elixir
|
|
@five_min_in_seconds 60 * 5
|
|
|
|
defp unix_five_min_from_now do
|
|
unix_now = DateTime.to_unix(DateTime.utc_now(), :second)
|
|
unix_now + @five_min_in_seconds
|
|
end
|
|
```
|
|
|
|
We removed the unnecessary comments. We also added a `@five_min_in_seconds` module attribute, which serves the additional purpose of giving a name to the "magic" number `60 * 5`, making the code clearer and more expressive.
|
|
|
|
#### Additional remarks
|
|
|
|
Elixir makes a clear distinction between **documentation** and code comments. The language has built-in first-class support for documentation through `@doc`, `@moduledoc`, and more. See the ["Writing documentation"](../getting-started/writing-documentation.md) guide for more information.
|
|
|
|
## Long parameter list
|
|
|
|
TODO.
|
|
|
|
## Complex branching
|
|
|
|
TODO.
|
|
|
|
## Complex else clauses in with
|
|
|
|
TODO.
|
|
|
|
## Complex extractions in clauses
|
|
|
|
TODO.
|
|
|
|
## Dynamic map fields access
|
|
|
|
TODO.
|
|
|
|
## Dynamic atom creation
|
|
|
|
TODO.
|
|
|
|
## Namespace trespassing
|
|
|
|
TODO.
|
|
|
|
## Speculative assumptions
|
|
|
|
TODO.
|