vertical ordering of functions

[Hans Georg Schaathun]

On Tue, 3 May 2011 18:08:27 -0400, Jabba Laci
  <jabba.laci at gmail.com> wrote:
:  I'm just reading Robert M. Martin's book entitled "Clean Code". In Ch.
:  5 he says that a function that is called should be below a function
:  that does the calling. This creates a nice flow down from top to
:  bottom.

My advice would be to order it in the same way as you would if you
were presenting the algorithm in a paper.

>From such a viewpoint, it depends on whether you consider the called
names to be terms which need definitions, or operations with an
intutive purpose, merely requiring an explanation (implentation) of
how it is done.

In a paper that means that definitions must come before the theorems
and lemmata very often between the theorem and its proof.  If you
don't write papers, that may not be particularly useful :-)

In programming, it means that names which have self-explanatory name
may very well be called first and defined later.  The caller will
give a high-level view of what is going on.  The callees are building
blocks whose purpose can be understood immediately, and whose inner
workings can be sought further down the file.  Fundamental definitions
which may be as easy to implement as explain may often come first.

The question here, is didactics and not programming per se.
A simple rule does not make complex code significantly easier to read,
but a thought structure of the code (with comments and choice of names)
over-all does.

And let's not forget that calls may be circular or otherwise convolved
in a way that does not allow consistent sorting of caller before/after
callee.

-- 
:-- Hans Georg