How do you work with nested modules?

So what’s the idiomatically correct way to do nested modules? I know when applications you tend to do it the first way and follow the directory hierarchy, but when to choose one over the other because I do see it done both ways? The only time I do it the second way is if all I need are a bunch of structs.

defmodule Foo do
   ...
end

then

defmodule Foo.Bar do
    ...
end

VS

defmodule Foo do
 
    defmodule Foo.Bar do
        ...
    end
    ....
end
1 Like

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.

4 Likes

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

3 Likes

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.

6 Likes

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
3 Likes

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.

4 Likes

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.

1 Like

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.

1 Like

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.

Yes, in a strict code sense, it’s three declarations, but we’re talking about someone else reading the code. So the outer module is like a document body, and the inner module is like a paragraph.

This convention is targeted toward the reader of the code, so if they’re working in the module, they will already know to use %State{}. The idea is that the reader should be able to search for State in the code and have a single place to look to find out what it is.

This is only true for functions:

defmodule TestModule do
  defstruct [:test]

  @type x :: integer()
  @type y :: integer()
  @type z :: integer()
  @type a :: integer()
  @type n :: integer()
  @type m :: integer()
  @type o :: integer()

  @spec hello_world :: :ok
  def hello_world do
    :ok
  end

  @type t :: %__MODULE__{test: nil | :test}
end

This will not raise any errors in v1.13.3

Of course, but it will raise compileError if your struct field names drift.