Reading Code

2022 Mar 20 See all posts

Writing code is similar to writing, and as such you can pick a lot of insights from reading other programmers' code. Following are some notes around that...

Understand the code structure and components

• The first 1-2 layers of complexity should be BFS. Meaning you should aim for breadth and covering that layer (or level) of all components.
• The key is to capture the most impactful arc of what the code is doing.
• Resist the pull into a rabbit hole of a particular component. During the first few times, focus on "what's happening" rather than "how it's done (implemented)" – essentially limited DFS for first few scans of the code.

Document

• Document the important files, classes, terminology, components.

Active vs Passive code reading

• Hacking produces better comprehension than passive, linear reading. Solid understanding emerges from active exploration, critical examination, repition and synthesis.
• you can have a specific problem, which you treat like a kata and mindfully implement it multiple times.
• focus on guiding exploration – features in your codebase that are good exercises for re-implementation.
• Reading, building and running the code – without the latter 2 steps, you're missing a key component in comprehension.

Some Example Strategies

• From Michael Kerrisk (author of TLPI): take time to read the documentation (if it exists) and then write small (but increasingly large) test programs until you become confident of your understanding of the software.
• From Levi Aul (easily the best engineer I've ever worked with): There are two ways to solve a problem – solving it on top of existing framework (treating it as a blackbox, only concerned about API); and then opening up the existing base and extend the components to solve the problems (like writing a postgres extension). The latter can teach you a lot about how X works which would directly inform any future work with it.
• Benjamin Franklin method (applied to reading programming resources):
  • read the programming book as normal. When you get to a code sample, read it over.
  • Then close the book
  • Then try to type it up. You'll be forced to think/learn about the structure of the code.

Get at it consistently

• you're not going to soak in everything in a day. All the structure, tips and techniques aside, nothing beats exploring the codebase you're working on with consistency.
• There are infact code reading clubs. This "one c file from BSD project everyday" apparently got the person to notice inconsistencies and eventually the contributions went from opportunistic to more goal-oriented.

Practice Concepts

• This is really a sort of meta-preparation. Nothing beats slow practice of concepts. Seek exercise that has some practice problems and then go ahead and solve them. That's the only way to properly assimilate information over a long term.

---

Others insights about reading code

• typicall the focus is on the ability to find right information. Knowing what to ignore is under-emphasized, and the desire to modify provides a powerful "ignore this" heuristic.
• Often you have something useful to tell the user, but no obvious place to put it so that the reader can see it at the right time. Schelling points in codebase is an interesting idea to help solve this.