How to annotate unfamiliar code to understand it faster

Writing Makes You Read Better

The fastest way to understand unfamiliar code is to annotate it as you read. Writing forces precision — you can't write a vague summary without realizing you don't understand the code yet.

The Annotation Technique

// Original code — opaque on first read
function process(data) {
  return data
    .filter(x => x.active && x.score > 0)
    .sort((a, b) => b.score - a.score)
    .slice(0, 10)
    .map(x => ({ id: x.id, name: x.name, rank: x.score }));
}

// After annotation — purpose is clear
function process(data) {
  return data
    .filter(x => x.active && x.score > 0)  // keep active, non-zero items
    .sort((a, b) => b.score - a.score)      // sort descending by score
    .slice(0, 10)                           // top 10 only
    .map(x => ({ id: x.id, name: x.name, rank: x.score })); // reshape for API
  // Overall: returns top-10 active items ranked by score
}

Scratch Files and Hypothesis Testing

Create a scratch.js or notes.md in a gitignored location. Write your understanding as declarative statements: "This module is responsible for X. It is called by Y. It depends on Z." When you're wrong, fixing the statement cements the correct understanding.

Delete annotations before committing. Your job was to understand the code — not to add your reading notes to the codebase permanently.