Reference

How to read code

Most of the code you meet, you did not write — and an assistant adds more of it every day. The reader’s job is to know what a function DOES (not what its name suggests) and what would break if it changed. Here are the moves the lab drills. Open the reading lab →

  • Read the doc-comment first

    The `///` doc tells you what the author INTENDED. Read it before a line of code — it tells you what to expect, including at the edges (empty, zero, the boundary).

  • But trust the CODE, not the doc

    Docs drift. When the doc says “up to and including n” but the code uses `..<` (which stops before n), the code is what runs. A doc that disagrees with the code is a bug you just found by reading.

  • Read the signature

    The name, the parameters, and the return type are a contract. `clamp01(x) -> Int` promises a whole number in a range; `-> Int` division quietly throws away the remainder.

  • Read the loop

    `for x in xs` walks the ITEMS; `for x in 0..<xs.count` walks the POSITIONS. `..<` runs up to (not including) the end; `...` runs one more. A one-character difference changes the answer.

  • Read the license

    MIT, Apache-2.0, BSD-3-Clause each permit reuse WITH attribution — you must keep the copyright line and credit the authors. Reading the license is part of reading the library.

  • Ask: what breaks if this changes?

    You depend on this helper. If a new version removes a guard or moves a boundary, YOUR unchanged call can start crashing. Reading a dependency means reading how its changes ripple to you.

What to read in a helper you didn’t write

  • The guardIs there an `if x == 0 { return … }` protecting a divide or an index? Remove it and the caller crashes.
  • The boundaryIs it `< n` or `<= n`? `..<` or `...`? Off-by-one hides here.
  • Item vs positionDoes the loop use the value, or the index? They look alike and mean different things.
  • Whole vs decimal`Int` division truncates (7 / 2 is 3). The return type tells you.
  • The doc vs the codeDo they agree? If not, the code wins — and you found a real bug.

The snippets are original teaching examples in the style of small open-source helpers, with a real open license so you can practise reading one. The code is a teaching subset of the Swift language. Nothing you read leaves your device. Read a helper →