Reading the source

For years I treated dependencies as black boxes. I read the docs, copied the example, and moved on. Then a bug sent me into node_modules for the first time, and I never came back out.

Docs tell you the happy path

Documentation is written for the case the author imagined. The source is written for every case the code actually handles. When the two disagree, the source wins.

Reading it gives you three things docs rarely do:

1. The shape of the real API, including the parts nobody documented.
2. A feel for the author's taste, which tells you how to use the library well.
3. The confidence to patch or work around it when you must.

A small ritual

When I adopt a library now, I open its entry point and trace one call all the way down:

import { thing } from 'some-lib'


// then I go read what `thing` actually does
thing({ verbose: true })

It takes twenty minutes and saves hours later. Most code is more readable than you fear, and the act of reading it slowly makes you a better writer of your own.