def_layout - deterministic function layout via mix format

News Announcing
, , , , ,
1

I just published def_layout, a formatter plugin that lays out a module’s functions: callbacks first in source order, public functions alphabetical by name and arity, each private function just below its bottom-most caller.

Here’s the before/after that shows the tradeoff, on a GenServer:

# before (hand-ordered)
def start_link    # the entry point, conventionally first

@impl GenServer
def init

@impl GenServer
def handle_call({:get, key}, _from, state) do
  {:reply, fetch(state, key), state}
end

def take
def get
defp fetch

# after
@impl GenServer   # callbacks first, in source order
def init          # (alphabetical would flip these two)

@impl GenServer   # the attribute rides along
def handle_call({:get, key}, _from, state) do
  {:reply, fetch(state, key), state}
end

defp fetch        # private, sinks under its caller

def get           # publics, alphabetical
def start_link
def take

Yes, start_link lands mid-pack, wherever the alphabet drops it. That’s the honest cost of the rule, shown up front. Once you know publics are alphabetical you stop scanning for start_link; you jump to it. (The README FAQ takes this objection head-on - the section is literally titled “start_link should be first.”)

The payoff is the private layout: each private function directly under its bottom-most caller means you read a function and its helpers are right there, in call order, instead of scattered across the file or piled at the bottom.

def_layout orders by AST but moves source text by line span, so comments and attached @doc/@spec/@impl ride along with their function. Quokka and Styler order the directive block; def_layout orders the functions below it. They compose - list DefLayout first, so the other plugin formats last. (The README has the full comparison.)

I ran it across fourteen codebases before publishing - Phoenix and LiveView apps, Ash, Absinthe, Plug, Nx, and my own production code. The README’s “Tested on real code” section has the methodology, and the sweep script ships in the repo so you can point it at your own tree. Modules it can’t reorder safely (an Ecto schema, a plug pipeline) are skipped - still formatted, just not laid out - and mix def_layout.skipped lists what was left alone and why.

Works with LSP format-on-save (tested with Expert in Neovim).

Setup is two lines:

# mix.exs
{:def_layout, "~> 0.1.0", only: [:dev, :test], runtime: false}

# .formatter.exs
[
  plugins: [DefLayout]
]

There are no ordering knobs. If you think public function order carries meaning worth maintaining by hand, this isn’t the tool for you. That’s by design. (The FAQ covers that one too.)

Requires Elixir 1.16+.

Hex: def_layout | Hex
Docs: def_layout v0.1.0 — Documentation

7 Likes