[steinuil]

> The leaf functions come first, and the global interface functions are last.

To me that is backwards. I prefer code written in a topological order for a number of reasons:

- It mirrors how you write code within a function.

- It's obvious where you should put that function in the module.

- Most importantly, it makes circular dependencies between pieces of code in a module really obvious.

I'm generally not a fan of circular dependencies, because they make codebases much more entangled and prevent you from being able to understand a module as a contained unit. In Python they can even lead to problems you won't see until you run the code[0], but circular imports are probably so common that current type checkers disable that diagnostic by default[1].

I think languages that don't support forward references (C, but also OCaml and SML) let me apply the "principle of least surprise" to circular dependencies. OCaml even disallows recursive dependencies between functions unless you declare the functions with "let rec fn1 = .. and fn2 = ..", which may be a bit annoying while you're writing the code but it's important information when you're reading it.

[0]: https://gist.github.com/Mark24Code/2073470277437f2241033c200...

[1]: https://microsoft.github.io/pyright/#/configuration?id=type-... (see reportImportCycles)