I'm not sure what you have in mind, but if you put your "main" Python code inside a "main()" function, you can put that main() wherever you want (like at the top). You just have to call it at the bottom of the file, below anything it refers to.
Yeah: to me, it really depends on the story being told, and frankly even then it might depend a bit on the proclivities and interests of the person reading the story.
The one thing I'd say almost never works for reading code, though, is the thing people seem to insist is best practice: scattering everything into a hundred separate files with no clear order at all!
Trying to understand that code is like sitting down to an encyclopedia and then being asked to somehow use it to answer to the ultimate question of life, the universe, and everything.
The worst is when you grep the code for "main" in an attempt to at least come to your own idea of order, and it turns out that a bunch of files have their own main functions for various unit tests in files the build system just happens to ignore :/.
That's part of why Knuth came up with Literate Programming: he wanted to be able to present the reader of his code with a coherent order that makes sense to understand the project.
Given the strict formal requirements on order of languages like Pascal, Knuth had to come up with a clever preprocessing scheme to satisfy both the reader and the compiler. (See his tool, https://en.wikipedia.org/wiki/Web_(programming_system) )
Modern languages are a bit more flexible, but can still benefit from some re-ordering.
> The worst is when you grep the code for "main" in an attempt to at least come to your own idea of order, and it turns out that a bunch of files have their own main functions for various unit tests in files the build system just happens to ignore :/.
I used to use tools like grep a lot, but I found that my productivity really improved a lot when I set up an environment that supports 'jump to definition' and 'jump to references' etc.
You know, it's funny on grep: back 25 years ago, I used to spend a lot of time with my IDE and made sure it supported jumping to definitions and such, but I went in the opposite direction... when I sit down at your code base I want to be able to find what I'm looking for without figuring out how to get the perfect code explorer working first (and, frankly, I don't think that the usual implementations of "jump to definition" would handle a project file that contain multiple copies of the function and a ton of conditional build includes anyway). Do you have a recommendation? The #1 issue I run into is with Google projects that use Bazel, so it would have to support that...
Yes, it drives me nuts that e.g. Python makes you put the definitions before their use!