Add "namespaces" guidance to library guidelines (#10818)

Author: axelson

lib/elixir/pages/library-guidelines.md

@@ -180,6 +180,14 @@ That's because by reading the application in the module body and storing it in a
 
 If, for some reason, you must read the application environment at compile time, use `Application.compile_env/2`. Read [the "Compile-time environment" section of the `Application` module documentation](Application.html#module-compile-time-environment) for more information.
 
+### Avoid defining modules that are not in your "namespace"
+
+Even though Elixir does not formally have the concept of namespaces, a library should use its name as a "prefix" for all of its modules (except for special cases like mix tasks). For example if the library's OTP application name is `:my_lib`, then all of its modules should start with the `MyLib` prefix, for example `MyLib.User`, `MyLib.SubModule`, and `MyLib.Application`.
+
+This is important because the Erlang VM can only load one instance of a module at a time. So if there are multiple libraries that define the same module, then they are incompatible with each other due to this limitation. By always using the library name as a prefix, it avoids module name clashes due to the unique prefix.
+
+Furthermore, when writing a library that is an extension of another library, you should avoid defining modules inside the parent's library namespace. For example, if you are writing a package that adds authentication to [`Plug`](https://github.com/elixir-plug/plug) called `plug_auth`, its modules should be namespaced under `PlugAuth` instead of `Plug.Auth`, so it avoid conflicts with `Plug` if it were to ever define its own authentication functionality.
+
 ### Avoid `use` when an `import` is enough
 
 A library should not provide `use MyLib` functionality if all `use MyLib` does is to `import`/`alias` the module itself. For example, this is an anti-pattern: