"If the story sucks, the execution sucks"

Hey there,

So how should you structure your Python programs?

If you're writing anything that goes beyond a few lines of code, how should you lay out your functions?

Is there a "structure to the chaos?"

Interesting thought on that topic from a newsletter member:

~~~

I have always felt that programming is telling a computer a story. 

If your story is good, the computer will execute it efficiently, if the story sucks, the execution sucks. 

I write code like I would write a technical paper, it has direction and flow, and you can tell when you have reached the conclusion of the story.

~~~

Cute! And true:

I've had good results with this approach. It works especially well for single-file automation or data crunching scripts. 

Imagine the following high-level logical flow for a simple report generator program:

1. Read input data
2. Perform calculations
3. Write report

Notice how each stage (after the first one) depends on some byproduct or output of its predecessor:

1. Read input data
2. Perform calculations (based on input data)
3. Write report (based on calculated report data)

You can either implement this logical flow from *the top down* or from *the bottom up*.

If write your program bottom-up, your function layout will match the logic flow—it'll go from the fully independent building blocks to the ones that depend on their results.

Here's a sketch for a "bottom-up" implementation:

def read_input_file(filename):
    pass 

def generate_report(data):
    pass

def write_report(report):
    pass 

data = read_input_file('data.csv')
report = generate_report(data)
write_report(report)

This structure "makes sense," doesn't it?

We first need to read the input file before we can generate a report, and we need to generate the report before we can write it out to disk.

This logical structure is reflected in the program's layout.

(Or, in scary-sounding Computer Science terms: This is basically a topological sorting of the dependency graph.)

For a "top-down" approach you'd flip the same structure on its head and start with the highest-level building block first, fleshing out the details later:

def main():
    data = read_input_file('data.csv')
    report = generate_report(data)
    write_report(report)

def write_report(report):
    pass

def generate_report(data):
    pass

def read_input_file(filename):
    pass 

# Application entry point -> call main()
main()

See how I started with the high-level, "most dependent" functionality first this time around? 

The "main()" function at the top states clearly what this program is going to do—without having defined yet *how exactly* it will achieve the desired result.

Now, which approach is better, "top-down" or "bottom-up?"

I don't think there's much of a practical difference between them, to be honest. 

The important thing for me is that they both encode a logical narrative—they're both "telling the computer a story" and they have "direction and flow."

This is the key insight for me.

The worst thing one can do is deliberately obfuscating this logical structure, thereby killing the narrative:

def write_report(report):
    pass 

def read_input_file(filename):
    pass 

def generate_report(data):
    pass

(Yuck!)

Now, obviously I'm using a small "toy" example here—

But imagine what happens with programs that consist of 10, 100, 1000 steps in their "narrative" and they're organized incoherently?

Maybe it's my German need for order and stability speaking—but in my experience the result is usually utter chaos and madness.

Anyway, the more you practice this "narrative flow" mindset as a way of structuring your programs, the more natural it will feel and the more automatic it will become as a behavior while you're coding.

Plus, you can extend the idea to other "building blocks" like classes and modules as well...but more on that at some other time.

Happy Pythoning!

— Dan Bader