How do you work with nested modules?

I would say to let each module have its own file. And to follow the directory tree structure.
It makes it easier to find what you need later on.

Just be careful. You should double check what the name of that inside module is, it might not be what you think.

The only time I ever nest in the file is if it’s for something like state in a GenServer that will only be used internally by that GenServer.

defmodule SomeGenServer do
  use GenServer

  defmodule State do
    # Note that this is actually SomeGenServer.State
    defstruct [x: "", y: "", z: ""]
  end

  @impl true
  def init(_), do: {:ok, %State{}}

  @impl true
  def handle_call(:x_the_x, _from, state) do
    %{x: x} = state
    x = x_the_x(x)
    {:reply, x, %{state | x: x}}
  end

  def x_the_x(x) do
    to_string(x) <> to_string([Enum.random(?A .. ?z)])
  end
end

Otherwise, I define each module in its own file and have the directory structure match that nesting.

For this use-case, did you consider just directly including the struct and aliasing it, e.g:

defmodule MyMod do
  defstruct …
  alias __MODULE__, as: State
end

I’ve done it before, but it doesn’t feel as explicit. It’s kind of magic for magic’s sake. Thinking back to when I first started using Elixir, I would have been very confused by this because they appear as two separate “declarations”. So I would be looking for what State was and ask, “why is it just referring back to the module?” not realizing that the module itself is the struct. On the contrary, defining it as a nested module gives the beginner a clear understanding of where %State{} actually came from.

Why not just use the GenServer module itself, and assign it with @type state::%__MODULE__{...} ? If you’re including the struct matching in your function headers that does incur a runtime cost.

Nothing wrong with that, but it still has the same “two declarations” problem, so I stick to this style because it’s the most explicit to beginner me.

Huh? In my version I count:

• defstruct
• @type

In your version I count three

• defmodule
• defstruct
• @type

Am I missing something?

No this should be

• defmodule
  • defstruct
  • @type

It’s a “single declaration” that encapsulates all of the information about the struct. There is nothing else there to confuse the reader (like other types, function definitions, etc). There also isn’t a way for the type declaration to accidentally drift away from the defstruct. Something to keep in mind too is that not everyone types their code, not everyone remembers to update the types, and not all beginners have a full understanding of what the types mean. Nesting the module this way (albeit rare because I don’t usually make “state structs”) is just a convention I have adopted that causes less confusion for those unfamiliar with Elixir.

Ok. I still count three declarations. Shrug. I think that when I was a beginner a lot of that stuff would have be super confusing, starting with what does it mean for a module to be nested (I remember being mind blown when I learned you could do that). The aliasing rules are also implicit and not entirely obvious (the state module becomes MyModule.State and is implicitly aliased as State, but only in the scope of MyModule). Already OP in this thread has made that mistake…

There also isn’t a way for the type declaration to accidentally drift away from the defstruct.

This is compile-time checked by elixir.