Python is one of many languages that will let you define your module’s functions in whatever order you want. If your language of choice allows functions to be order independent, what order should you choose?
Let’s illustrate what I’m talking about so that we’re all on the same page. First, here’s a Python example that puts the helper function first.
And here’s a version that does the opposite.
Both versions work. I believe the latter version is better. Here’s why.
My assertion seems rather arbitrary, so what is it about the latter version that makes it better?
In my example,
parent is a more abstract function.
In the call stack,
it’s the first to be called,
and its implementation is a call to another function.
I think that having a more abstract function first allows you
to spend less time thinking about the code.
I think we need a more involved example because the short version is too short to reveal any problems.
Imagine that your working at a pizzeria software company and your customers are reporting a problem with your system (work with me here). The complaint: any order for pepperoni topping produces a pizza with anchovies instead.
Your boss has asked you to fix the problem.
The entire company runs on a single Python module
and the moneymaker is your proprietary
(is this absurd enough yet?)
pizza = toss_dough()
pizza = add_toppings(pizza, order)
# Thousands of lines of code below here,
# including toss_dough, add_toppings, bake, etc.
Each of those five helper functions has dozens
of their own helpers.
The process of calling
make_pizza is positively labyrinthine.
Did I mention this is your first day at the job and you don’t know this code yet? It sounds silly, but I can confidently say that, as a professional software developer, you encounter code all the time that you’ve never seen before. Software systems are generally big.
If you needed to solve this problem quickly, where would you look to start?
By putting the most abstract function first, you can immediately understand the high level flow through the system. The function acts like a table of contents of whatever else you’re bound to find.
Knowing that you need to deal with toppings,
you can dig into
as you’re debugging through the problem
and continue to dig through the layers
which get progressively farther and farther into the file.
What if this problem was flipped around
and all the helper functions were first?
I think you’d likely take longer to orient yourself,
since you wouldn’t have seen the main
until you reach the bottom
of the file.
you’d lack the context about the pieces
and be building up your mental model
from the entire tree of functions
from the bottom of the call stack.
with most abstract at the bottom,
you’re reading stuff
that you didn’t need to read.
Your mission is to fix whatever is wrong
If the helpers were roughly in clusters associated
with the five main functions
then, at minimum,
you had to get through
before you got to
With the most abstract first ordering,
you can avoid this problem
and jump straight to the functions
that are most relevant to the task
(especially when using the jump to definition features available
to most IDEs or text editors).
The most abstract function first ordering means that you are better able to get into the abstractions that are pertinent and skip the other abstractions and irrelevant implementation details.
I hope you noticed that this is an opinion piece. While I think having the most abstract functions first is better, there are times when it’s not appropriate.
First, your language may not support this ordering.
I’ve been working with Lua recently, and function order matters in that language!
local function parent()
local function child()
This version is broken!
$ lua example.lua
lua: example.lua:2: global 'child' is not callable (a nil value)
example.lua:2: in local 'parent'
example.lua:9: in main chunk
[C]: in ?
Second, try to respect the conventions of existing projects.
I’m trying to get Lua support included with pre-commit with this PR. In my initial implementation, I goofed up and put the most abstract functions first and failed to notice that other modules did the opposite. Anthony, pre-commit’s maintainer, pointed out the difference in the review, and I was happy to correct my mistake. Sometimes, consistency is a better quality to maintain than some personal design ideal.
Those are my thoughts on this design subject. I hope these ideas help you think through this topic too. Disagree with me? That’s cool with me. If I helped you solidify your ideas, mission accomplished.
Thanks for reading! Chat with me about this on Twitter! I’m curious what you think.