Clarify best practices and update anti-patterns list

Author: josevalim

lib/elixir/pages/anti-patterns/code-anti-patterns.md

@@ -34,7 +34,8 @@ You could refactor the code above like this:
 @five_min_in_seconds 60 * 5
 
 defp unix_five_min_from_now do
-  unix_now = DateTime.to_unix(DateTime.utc_now(), :second)
+  now = DateTime.utc_now()
+  unix_now = DateTime.to_unix(now, :second)
   unix_now + @five_min_in_seconds
 end
 ```
@@ -45,75 +46,6 @@ We removed the unnecessary comments. We also added a `@five_min_in_seconds` modu
 
 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.
 
-## Complex branching
-
-#### Problem
-
-When a function assumes the responsibility of handling multiple errors alone, it can increase its cyclomatic complexity (metric of control-flow) and become incomprehensible. This situation can configure a specific instance of "Long function", a traditional anti-pattern, but has implications of its own. Under these circumstances, this function could get very confusing, difficult to maintain and test, and therefore bug-proneness.
-
-#### Example
-
-An example of this anti-pattern is when a function uses the `case` control-flow structure or other similar constructs (for example, `cond` or `receive`) to handle variations of a return type. This practice can make the function more complex, long, and difficult to understand, as shown next.
-
-```elixir
-def get_customer(customer_id) do
-  case SomeHTTPClient.get("/customers/#{customer_id}") do
-    {:ok, %{status: 200, body: body}} ->
-      case Jason.decode(body) do
-        {:ok, decoded} ->
-          %{
-            "first_name" => first_name,
-            "last_name" => last_name,
-            "company" => company
-          } = decoded
-
-          customer =
-            %Customer{
-              id: customer_id,
-              name: "#{first_name} #{last_name}",
-              company: company
-            }
-
-          {:ok, customer}
-
-        {:error, _} ->
-          {:error, "invalid response body"}
-      end
-
-    {:error, %{status: status, body: body}} ->
-      case Jason.decode(body) do
-        %{"error" => message} when is_binary(message) ->
-          {:error, message}
-
-        %{} ->
-          {:error, "invalid response with status #{status}"}
-      end
-  end
-end
-```
-
-The code above is complex because the `case` clauses are long and often have their own branching logic in them. With the clauses spread out, it is hard to understand what each clause does individually and it is hard to see all of the different scenarios your code pattern matches on.
-
-#### Refactoring
-
-As shown below, in this situation, instead of concentrating all error handling within the same function, creating complex branches, it is better to delegate each branch to a different private function. In this way, the code will be cleaner and more readable.
-
-```elixir
-def get_customer(customer_id) do
-  case SomeHTTPClient.get("/customers/#{customer_id}") do
-    {:ok, %{status: 200, body: body}} ->
-      http_customer_to_struct(customer_id, body)
-
-    {:error, %{status: status, body: body}} ->
-      http_error(status, body)
-  end
-end
-```
-
-Both `http_customer_to_struct(customer_id, body)` and `http_error(status, body)` above contain the previous branches refactored into private functions.
-
-It is worth noting that this refactoring is trivial to perform in Elixir because clauses cannot define variables or otherwise affect their parent scope. Therefore, extracting any clause or branch to a private function is a matter of gathering all variables used in that branch and passing them as arguments to the new function.
-
 ## Complex `else` clauses in `with`
 
 #### Problem

lib/elixir/pages/anti-patterns/what-anti-patterns.md

@@ -38,4 +38,4 @@ Each anti-pattern is documented using the following structure:
 
 The initial catalog of anti-patterns was proposed by Lucas Vegi and Marco Tulio Valente, from [ASERG/DCC/UFMG](http://aserg.labsoft.dcc.ufmg.br/). For more info, see [Understanding Code Smells in Elixir Functional Language](https://github.com/lucasvegi/Elixir-Code-Smells/blob/main/etc/2023-emse-code-smells-elixir.pdf) and [the associated code repository](https://github.com/lucasvegi/Elixir-Code-Smells).
 
-Additionally, the Security Working Group of the [Erlang Ecosystem Foundation](https://erlef.github.io/security-wg/) publishes [documents with security resources and best-practices of both Erland and Elixir, including detailed guides for web applications](https://erlef.github.io/security-wg/).
+Additionally, the Security Working Group of the [Erlang Ecosystem Foundation](https://erlef.github.io/security-wg/) publishes [documents with security resources and best-practices of both Erlang and Elixir, including detailed guides for web applications](https://erlef.github.io/security-wg/).

lib/elixir/pages/getting-started/alias-require-and-import.md

@@ -112,7 +112,7 @@ end
 
 In the example above, the imported `List.duplicate/2` is only visible within that specific function. `duplicate/2` won't be available in any other function in that module (or any other module for that matter).
 
-Note that `import`s are generally discouraged in the language. When working on your own code, prefer `alias` to `import`.
+While `import`s can be a useful for frameworks and libraries to build abstractions, developers should generally prefer `alias` to `import` on their own codebases, as aliases make the origin of the function being invoked clearer.
 
 ## use