Update docs for module attributes

It is not necessary to push module attributes as a mechanism
for constants. In fact, regular functions are a better default
for constants in the majority of the cases.

Author: josevalim

lib/elixir/lib/kernel.ex

@@ -3547,37 +3547,6 @@ defmodule Kernel do
       def example1, do: files()[:example1]
       def example2, do: files()[:example2]
 
-  ## Attention! Compile-time dependencies
-
-  Keep in mind references to other modules, even in module attributes,
-  generate compile-time dependencies to said modules.
-
-  For example, take this common pattern:
-
-      @values [:foo, :bar, :baz]
-
-      def handle_arg(arg) when arg in @values do
-        ...
-      end
-
-  While the above is fine, imagine if instead you have actual
-  module names in the module attribute, like this:
-
-      @values [Foo, Bar, Baz]
-
-      def handle_arg(arg) when arg in @values do
-        ...
-      end
-
-  The code above will define a compile-time dependency on the modules
-  `Foo`, `Bar`, and `Baz`, in a way that, if any of them change, the
-  current module will have to recompile. In such cases, it may be
-  preferred to avoid the module attribute altogether:
-
-      def handle_arg(arg) when arg in [Foo, Bar, Baz] do
-        ...
-      end
-
   """
   defmacro @expr
 

lib/elixir/pages/getting-started/module-attributes.md

@@ -1,12 +1,11 @@
 # Module attributes
 
-Module attributes in Elixir serve three purposes:
+Module attributes in Elixir serve two purposes:
 
-1. They serve to annotate the module, often with information to be used by the user or the VM.
-2. They work as constants.
-3. They work as a temporary module storage to be used during compilation.
+1. They serve to annotate the module and its functions.
+2. They work as a temporary module storage to be used during compilation.
 
-Let's check each case, one by one.
+Let's check these examples.
 
 ## As annotations
 
@@ -64,11 +63,11 @@ iex> h Math.sum # Access the docs for the sum function
 
 We also provide a tool called [ExDoc](https://github.com/elixir-lang/ex_doc) which is used to generate HTML pages from the documentation.
 
-You can take a look at the docs for `Module` for a complete list of supported attributes. Elixir also uses attributes to define [typespecs](../references/typespecs.md), which can be used to declare contracts between modules later.
+You can take a look at the docs for `Module` for a complete list of supported attributes. Elixir also uses attributes to annotate our code with [typespecs](../references/typespecs.md).
 
-## As "constants"
+## As temporary storage
 
-Elixir developers often use module attributes when they wish to make a value more visible or reusable:
+So far, we have seen how to define attributes, but how can read them? Let's see an example:
 
 ```elixir
 defmodule MyServer do
@@ -96,8 +95,8 @@ defmodule MyServer do
   def second_data, do: @my_data
 end
 
-MyServer.first_data #=> 14
-MyServer.second_data #=> 13
+MyServer.first_data() #=> 14
+MyServer.second_data() #=> 13
 ```
 
 > Do not add a newline between the attribute and its value, otherwise Elixir will assume you are reading the value, rather than setting it.
@@ -128,9 +127,9 @@ defmodule MyApp.Status do
 end
 ```
 
-This can be useful for pre-computing constant values, but it can also cause problems if you're expecting the function to be called at runtime. For example, if you are reading a value from a database or an environment variable inside an attribute, be aware that it will read that value only at compilation time. However, note you cannot invoke functions defined in the same module as part of the attribute itself, as those functions have not yet been defined.
+This can be useful for pre-computing values and then injecting its results into the module. This is what we mean by temporary storage: after the module is compiled, the module attribute is discarded, except for the functions that have read the attribute. Note you cannot invoke functions defined in the same module as part of the attribute itself, as those functions have not yet been defined.
 
-Every time an attribute is read inside a function, Elixir takes a snapshot of its current value. Therefore if you read the same attribute multiple times inside multiple functions, you may end-up making multiple copies of it. That's usually not an issue, but if you are using functions to compute large module attributes, that can slow down compilation. The solution is to move the attribute to shared function. For example, instead of this:
+Every time an attribute is read inside a function, Elixir takes a snapshot of its current value. Therefore if you read the same attribute multiple times inside multiple functions, you may end-up making multiple copies of it. Generally speaking, you want to avoid reading the same attribute multiple times and instead move it to shared function. For example, instead of this:
 
 ```elixir
 def some_function, do: do_something_with(@example)
@@ -145,25 +144,33 @@ def another_function, do: do_something_else_with(example())
 defp example, do: @example
 ```
 
-If `@example` is cheap to compute, it may be even better to skip the module attribute altogether, and compute its value inside the function.
-
-### Accumulating attributes
-
-Normally, repeating a module attribute will cause its value to be reassigned, but there are circumstances where you may want to [configure the module attribute](`Module.register_attribute/3`) so that its values are accumulated:
-
-```elixir
-defmodule Foo do
-  Module.register_attribute(__MODULE__, :param, accumulate: true)
-
-  @param :foo
-  @param :bar
-  # here @param == [:bar, :foo]
-end
-```
-
-## As temporary storage
-
-To see an example of using module attributes as storage, look no further than Elixir's unit test framework called `ExUnit`. ExUnit uses module attributes for multiple different purposes:
+> #### Attributes as constants {: .warning}
+>
+> Sometimes developers want to use module attributes as constants, however, functions themselves play a better role. For example, instead of defining:
+>
+> ```elixir
+> @hours_in_a_day 24
+> ```
+>
+> Instead, you should prefer:
+>
+> ```elixir
+> defp hours_in_a_day(), do: 24
+> ```
+>
+> Or a public function if it needs to be shared between modules.
+>
+> This also holds true even for complex data structures. For example, if you need to define some configuration, you can define it as:
+>
+> ```elixir
+> defp system_config(), do: %{timezone: "Etc/UTC", locale: "pt-BR"}
+> ```
+>
+> Given data structures in Elixir are immutable, only a single instance of the data structure above is allocated, and shared across all functions calls, since it doesn't depend on any expression.
+
+## Going further
+
+Libraries and frameworks can leverage module attributes to provide custom annotations. To see an example, look no further than Elixir's unit test framework called `ExUnit`. ExUnit uses module attributes for multiple different purposes:
 
 ```elixir
 defmodule MyTest do
@@ -177,8 +184,8 @@ defmodule MyTest do
 end
 ```
 
-In the example above, `ExUnit` stores the value of `async: true` in a module attribute to change how the module is compiled. Tags are also defined as `accumulate: true` attributes, and they store tags that can be used to setup and filter tests. For example, you can avoid running external tests on your machine because they are slow and dependent on other services, while they can still be enabled in your build system.
+In the example above, `ExUnit` stores the value of `async: true` in a module attribute to change how the module is compiled. Tags also work as annotations and they can be supplied multiple times, thanks to Elixir's ability to [accumulate attribute](`Module.register_attribute/3`). Then yuou can use tags to setup and filter tests, such as avoiding executing Unix specific tests while running your test suite on Windows.
 
-In order to understand the underlying code, we'd need macros, so we will revisit this pattern in the meta-programming guide and learn how to use module attributes as storage to allow developers to create Domain Specific Languages (DSLs).
+To fully understand how ExUnit works, we'd need macros, so we will revisit this pattern in the Meta-programming guide and learn how to use module attributes as storage for custom annotations.
 
 In the next chapters, we'll explore structs and protocols before moving to exception handling and other constructs like sigils and comprehensions.