declaration-order

Every File Has the Same Shape

A developer opening any file in your project should know where to look without searching. Constants at the top. Types next. Then classes. Then functions. Then the entry point. Every file. Every time. No exceptions.

When a codebase has no consistent declaration order, every file is a treasure hunt. The reader ctrl-F's for the class definition, scrolls past a helper function wedged between two constants, finds a type alias buried after the main function, and wonders if the person who wrote this was shuffling a deck of cards. This is not an organizational preference — it is a readability debt that compounds with every file added to the project.

The rules below establish a universal shape for files and classes. The specific language idioms vary; the principle does not.

File-Level Ordering

Every file follows this top-to-bottom sequence. Items that do not apply to a given file are simply absent — the order of what remains does not change.

1. Module docstring / file header comment
2. Imports (per the import-discipline skill)
3. Constants / module-level configuration
4. Type definitions / interfaces / type aliases
5. Classes
6. Module-level functions
7. Main / entry point (if applicable)

Why this order:

• Docstring first because the reader needs context before seeing code
• Imports second because they are the table of contents (see import-discipline)
• Constants third because they are referenced by everything below — defining them after the code that uses them forces the reader to jump upward
• Types fourth because classes and functions depend on them — a function signature referencing a type that is defined 200 lines later is a navigation failure
• Classes fifth because they are structural, self-contained units
• Functions sixth because they are the primary operations that use the types and constants above
• Entry point last because it is the culmination — it calls everything above, so it belongs at the bottom where the reader has already seen all dependencies