Definition Ordering

Some programming languages require that types/classes/function/subroutines be defined in bottom-up order: that is, one must fully define element E before one can define any elements that use E. However, many languages allow definitions to occur in a source file in any order, provided that any necessary forward declarations are included.

How do people order their definitions in source files, and why?

The goals of any deliberate ordering routine would be:

Readability -- The definitions are ordered in a way intended to ease comprehension by someone unfamiliar with the code.
Scanability -- The definitions are ordered in a way intended to make it easy for a programmer to quickly find definitions of interest.
Locality -- Putting related functions close to one another makes it easy for a programmer to navigate between them. Compiler/linker optimizations may be possible when functions are close to one another or ordered in a particular way.
Tool support -- When using "wizards" or other tools that automatically insert code into editable source files, or that process such code, it may be necessary to conform to conventions dictated by the tool.

With use of source code browsers, LiterateProgramming, and other tools, the physical order of definitions is often irrelevant to a reader. However, a logical ordering can help a reader to learn the relationships between definitions.

Some organizational techniques are:

Top-down -- Define highest-level functions at the top of the file, with lower-level functions defined later. This emphasizes an overview of the module's functionality, leaving the details for later.
Bottom-up -- Define lowest-level functions at the top of the file, with higher-level functions defined later. This emphasizes the low-level details of the module, first showing the pieces and then later showing how they are assembled.
Subsystem -- The source file is organized into groups of tightly related definitions. Each group often has a big block comment that acts as a visual boundary and describes the group.
One per file -- Some people adopt a rule of having only one function or subroutine per source file. This practice is becoming less common, but is still used in some structured-programming environments and in library implementations. The benefits are that the name of the file usually matches the name of the defined element, making it easy to find, and it is easier for linkers to exclude unused object code from an executable.
Haphazard -- Define new items wherever is convenient, usually in the blank space above or below the last element examined. This emphasizes locality.
Alphabetical -- Not very helpful for learning the relationships between elements, but it does help you find an element when you know its name.
Historical -- Each new element is added to the end of the file, leaving older elements at the top. Automated source code generation tools usually follow this practice. This gives a reader some idea of the history of the file's development, and tends to put the implementation of the most important functionality at the top of the file and new features and bug fixes at the bottom.
Visibility or Protection Level -- Public elements first, followed by protected/package elements, then private elements. The reverse order (private-to-public) is also seen.