"Using application configuration for libraries" added (Anti-patterns …

…documentation) (elixir-lang#12944)

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

@@ -279,4 +279,59 @@ A common practice followed by the community is to make the non-raising version t
 
 ## Using application configuration for libraries
 
-TODO
+#### Problem
+
+The [*application environment*](https://hexdocs.pm/elixir/Application.html#module-the-application-environment) can be used to parameterize global values that can be used in an Elixir system. This mechanism can be very useful and therefore is not considered an anti-pattern by itself. However, library authors should avoid using the application environment to configure their library. The reason is exactly that the application environment is a **global** state, so there can only be a single value for each key in the environment for an application. This makes it impossible for multiple applications depending on the same library to configure the same aspect of the library in different ways.
+
+#### Example
+
+The `DashSplitter` module represents a library that configures the behavior of its functions through the global application environment. These configurations are concentrated in the *config/config.exs* file, shown below:
+
+```elixir
+import Config
+
+config :app_config,
+  parts: 3
+
+import_config "#{config_env()}.exs"
+```
+
+One of the functions implemented by the `DashSplitter` library is `split/1`. This function aims to separate a string received via a parameter into a certain number of parts. The character used as a separator in `split/1` is always `"-"` and the number of parts the string is split into is defined globally by the application environment. This value is retrieved by the `split/1` function by calling `Application.fetch_env!/2`, as shown next:
+
+```elixir
+defmodule DashSplitter do
+  def split(string) when is_binary(string) do
+    parts = Application.fetch_env!(:app_config, :parts) # <= retrieve parameterized value
+    String.split(string, "-", parts: parts)             # <= parts: 3
+  end
+end
+```
+
+Due to this parameterized value used by the `DashSplitter` library, all applications dependent on it can only use the `split/1` function with identical behavior about the number of parts generated by string separation. Currently, this value is equal to 3, as we can see in the use examples shown below:
+
+```elixir
+iex> DashSplitter.split("Lucas-Francisco-Vegi")
+["Lucas", "Francisco", "Vegi"]
+iex> DashSplitter.split("Lucas-Francisco-da-Matta-Vegi")
+["Lucas", "Francisco", "da-Matta-Vegi"]
+```
+
+#### Refactoring
+
+To remove this anti-pattern and make the library more adaptable and flexible, this type of configuration must be performed via parameters in function calls. The code shown below performs the refactoring of the `split/1` function by accepting [keyword lists](`Keyword`) as a new optional parameter. With this new parameter, it is possible to modify the default behavior of the function at the time of its call, allowing multiple different ways of using `split/2` within the same application:
+
+```elixir
+defmodule DashSplitter do
+  def split(string, opts \\ []) when is_binary(string) and is_list(opts) do
+    parts = Keyword.get(opts, :parts, 2) # <= default config of parts == 2
+    String.split(string, "-", parts: parts)
+  end
+end
+```
+
+```elixir
+iex> DashSplitter.split("Lucas-Francisco-da-Matta-Vegi", [parts: 5])
+["Lucas", "Francisco", "da", "Matta", "Vegi"]
+iex> DashSplitter.split("Lucas-Francisco-da-Matta-Vegi") #<= default config is used!
+["Lucas", "Francisco-da-Matta-Vegi"]
+```