Document it!

It will pay back.

Documenting modules and methods in Elixir (or any language, really) isn’t just about making your code look professional — it has very real, practical benefits for you, your team, and even your future self.

Documentation serves as a contract for how a function should behave.

When working in a team, people don’t need to guess about the inputs/outputs, side effects, or error conditions.

Saves time in code reviews — reviewers can focus on how well something is implemented, not what it even does.

🍳 Recipe 6: Documentation and Specs

defmodule LoggerUtils do
  @moduledoc "Helper functions for logging"

  @doc "Prints a formatted debug message"
  def debug(msg), do: IO.puts("[DEBUG] #{msg}")
end

📝 Use @moduledoc and @doc to self-document your code.

Works great with h in IEx:

iex> h LoggerUtils.debug

💡 Pro Tip: If your module is a library - good docs are your “user interface”, developers will prefer well-documented libraries, even if competitors have slightly more features.

🔥 Real-world example

defmodule Comixone.Utils.Url do
  @moduledoc """
  Utility functions for URL manipulation.
  """

  @doc """
  Fixes a given URL by ensuring it has a valid scheme or is prefixed with `root_url`.

  ## Parameters:
    - `url` (String.t()): The URL to be processed.
    - `opts` (Keyword.t()): A keyword list of options.
      - `:root_url` (String.t(), required) - The base URL to prepend if `url` is relative.

  ## Examples

      iex> Comixone.Utils.Url.fix_url("http://example.com", root_url: "https://base.com")
      "http://example.com"

      iex> Comixone.Utils.Url.fix_url("/path", root_url: "https://base.com")
      "https://base.com/path"

      iex> Comixone.Utils.Url.fix_url("path", root_url: "https://base.com")
      "https://base.com/path"

  """
  @spec fix_url(String.t(), keyword()) :: String.t()
  def fix_url("http://" <> _ = url, _opts), do: url
  def fix_url("https://" <> _ = url, _opts), do: url

  def fix_url(url, opts) do
    root_url = Keyword.fetch!(opts, :root_url)
    root_url <> ensure_leading_slash(url)
  end

  @doc """
  Ensures the given URL starts with a leading `/`.

  ## Parameters:
    - `url` (String.t()): The URL or path to modify.

  ## Examples

      iex> Comixone.Utils.Url.ensure_leading_slash("/path")
      "/path"

      iex> Comixone.Utils.Url.ensure_leading_slash("path")
      "/path"

  """
  @spec ensure_leading_slash(String.t()) :: String.t()
  defp ensure_leading_slash("/" <> _ = url), do: url
  defp ensure_leading_slash(url), do: "/" <> url
end