Tendril Function Order

I think the most readable order for functions in a source-code file is:

• Put the top-level functions in the order in which they appear in the program’s story.
• Immediately after each function, put the helper functions it calls.
• Apply the same rule recursively where practical.

For example:

prepare_drop_sha256_identifiers

  calculate_drop_sha256_identifier

    normalize_drop_path

  save_drop_sha256_identifiers

process_next_top_level_thing

  its_helper

I’m calling this Tendril Function Order. Each top-level function is a stem, and its helpers grow beneath it like tendrils.

Technically, it is roughly a depth-first, pre-order traversal of the file’s call graph. 

The result is that the file reads like an expanding outline. I first see what the program does. When a function mentions a detail, I find that detail immediately below it. Then I return to the next part of the high-level story.

Shared helpers can go beneath the first important caller. Recursive calls and tangled call graphs require judgment.