Engineering Craft › Developer Tooling

Reading Library Source Code

Reading a library's code when its docs don't answer your question.

Also known as: reading source, source diving

Reading a library’s source code is often the fastest way to answer a question the documentation doesn’t cover, such as what an edge case does, why an error appears, or which default applies. The code is the one description that’s guaranteed to match what the library does.

A practical approach starts from the public surface. Find the function you call, follow it to the place it does its work, and note the branches that matter for your case. Tests in the library are often the best examples of how it’s meant to be used.

# Find where a function is defined in an installed package
grep -rn "def parse_config" "$(python -c 'import site; print(site.getsitepackages()[0])')/mylib"

The trade-off is time. A large library can take hours to understand, and internal code can change between versions, so conclusions drawn from one version may not hold for the next. Reading also tempts you to depend on internal details that aren’t part of the public interface.

The classic mistake is building on a private function because it happens to do what you need. Private code can change without notice. When the behaviour matters, check whether a public option exists, and pin the version you verified against. A language server helps by jumping straight to definitions in your editor.