Formatting

Formatting is not decoration — it is communication. The way a file is laid out tells a reader, before they parse a single expression, what matters, what depends on what, and where to look next. A well-formatted file reads like a well-organized issue of the Daily Prophet: headline first, details below, related stories grouped together. This file covers the layout rules that carry the most weight, and where to stop arguing and let tooling decide.

For what goes inside the functions you're ordering, see functions; for the names that make the layout legible, meaningful-names.

Vertical ordering — the newspaper / stepdown rule

Well-ordered code reads like a book: the logic flows from top to bottom, and a reader grasps the intent of the whole file without jumping around it. Read a file top to bottom and it should read like a newspaper: the headline at the top, then the story in decreasing altitude. Put the highest-level function first, and place each function it calls just below it, so the reader descends from summary into detail without ever scrolling up. This is the stepdown rule — every function is followed by the ones it calls, one level of abstraction at a time. Group related functions by purpose so a reader can skim the headlines and dive only where they need to.

// Bad — details first, headline buried; the reader scrolls up to make sense of it
const rememberPassword = (student: Student): boolean => {
  return student.house === House.Ravenclaw
}

const requiresRiddle = (door: CommonRoomDoor): boolean => {
  return door.house === House.Ravenclaw
}