top-down-typescript

Top-Down TypeScript Coding Style

General Rules

• Dead (unused) code SHOULD NOT be kept (YAGNI principle).
• Do not write multiple consecutive blank lines.
• Changes to linter rules MUST be discussed before being implemented.
• Code SHOULD NOT contain commented-out code, unless a comment explains why.

Code Organization

Usage comes first, implementation after. Exception: with inheritance — when an interface extends another, write the parent first.

• Order code top-down: each file reads as a story, from entry point to leaves. The reader meets the highest-level thing first, then drills down into its dependencies:

  // 1. Imports
  import { ... } from "...";
  
  // 2. Module-level constants and variables (exported first, then internal)
  export const PUBLIC_CONST = ...;
  const INTERNAL_CONST = ...;
  
  // 3. Shared types — main type first, then types it references
  export interface MainType {
    detail: DetailType;
  }
  export interface DetailType { ... }
  
  // 4. Entry-point (exported) function
  export function doThing() {
    stepOne();
    stepTwo();
  }
  
  // 5. Internal functions called by the entry point, in call order
  function stepOne() {
    stepOneHelper();
  }
  function stepOneHelper() { ... }
  
  function stepTwo() { ... }
  

• Module-level constants and variables (const, let, var value declarations at the top of the file — both exported and internal) MUST be placed immediately after imports, before any type definitions, functions, or classes. The reader sees them first and treats them as the file's configuration surface.

• Functions: write the caller first, then the functions it calls, recursively. A helper appears just below its caller, not grouped at the bottom of the file. If a helper is called by several siblings, place it after its first caller.

• Types: write the main (top-level) type first, then the types it references, recursively. Same top-down rule as functions.

• Types attached to a single function (or class, or other declaration) — i.e. used only in that one signature, like a MyComponentProps interface used only by MyComponent — must be placed immediately before that declaration, not in the top type block.

• Exports are not a sorting criterion on their own: a function being exported does not pull it to the top — its position is determined by who calls it. The entry points of a file are usually exported, which is why they tend to appear first, but that is a consequence of the top-down rule, not the rule itself.