Describe them as potential anti-patterns

Author: josevalim

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

@@ -1,6 +1,6 @@
 # Code-related anti-patterns
 
-This document outlines anti-patterns related to your code and particular Elixir idioms and features.
+This document outlines potential anti-patterns related to your code and particular Elixir idioms and features.
 
 ## Comments
 
@@ -295,6 +295,8 @@ defmodule PlugAuth do
 end
 ```
 
+#### Additional remarks
+
 There are few known exceptions to this anti-pattern:
 
   * [Protocol implementations](`Kernel.defimpl/2`) are, by design, defined under the protocol namespace

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

@@ -1,6 +1,6 @@
 # Design-related anti-patterns
 
-This document outlines anti-patterns related to your modules, functions, and the role they
+This document outlines potential anti-patterns related to your modules, functions, and the role they
 play within a codebase.
 
 ## Alternative return types

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

@@ -1,6 +1,6 @@
 # Meta-programming anti-patterns
 
-This document outlines anti-patterns related to meta-programming.
+This document outlines potential anti-patterns related to meta-programming.
 
 ## Large code generation by macros
 

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

@@ -1,6 +1,6 @@
 # Process-related anti-patterns
 
-This document outlines anti-patterns related to processes and process-based abstractions.
+This document outlines potential anti-patterns related to processes and process-based abstractions.
 
 ## Code organization by process
 

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

@@ -1,14 +1,14 @@
 # What are anti-patterns?
 
-Anti-patterns describe common mistakes or indicators of potential problems in code.
+Anti-patterns describe common mistakes or indicators of problems in code.
 They are also known as "code smells".
 
-The goal of these guides is to document known anti-patterns found in Elixir software
-and teach developers how to identify them and their limitations. If an existing piece
+The goal of these guides is to document potential anti-patterns found in Elixir software
+and teach developers how to identify them and their pitfalls. If an existing piece
 of code matches an anti-pattern, it does not mean your code must be rewritten.
-No codebase is free of anti-patterns and one should not aim to remove all
-anti-patterns of a codebase. The goal is to promote a discussion of potential
-pitfalls and provide alternatives into consideration.
+Sometimes, even if a snippet matches a potential anti-pattern and its limitations,
+it may be the best approach to the problem at hand. No codebase is free of anti-patterns
+and one should not aim to remove all of them.
 
 The anti-patterns in these guides are broken into 4 main categories:
 
@@ -36,6 +36,8 @@ Each anti-pattern is documented using the following structure:
   * **Refactoring:** Ways to change your code to improve its qualities. Examples of refactored
     code are presented to illustrate these changes.
 
+An additional section with "Additional Remarks" may be provided. Those may include known scenarios where the anti-pattern does not apply.
+
 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 Erlang and Elixir, including detailed guides for web applications](https://erlef.github.io/security-wg/).