Ask HN: How to understand the large codebase of an open-source project?

Hello All!

what are techniques you all used to learn and understand a large codebase? what are the tools you use?

Run the examples to see what it does, try to build something with it to get a deeper understanding of the depth of its capability, then finally dive into the code itself by fixing a bug or adding a feature or even just playing around and changing stuff. Join the developer channels and ask questions. People usually love it when you show an interest in what they've built.

The straightforward way to understand code is to work with it. That is to say, look at open tickets and try to implement the suggested functionality or fixes (or some of your own ideas).

The analytic approach is a bit more awkward, since you have no specific goals and need to make them up yourself. So you could pose questions like how a specific behaviour of the application comes about ("why does it do that when this happens?", "how does it do X?") and then try to answer those comprehensively, systematically (a format that works well for me is short snippets of code interleaved with explanations and arguments).

A bottom-up approach is generally easier, because your questions will give you information at the bottom (like specific application messages), which are generally easy to find (ag, grep). A good IDE can be helpful for navigating the code and finding call sites, especially in projects written in dynamic languages where such analyses can become kinda annoying. (However, in more awkward code bases analysers like PyCharm are quickly overwhelmed and are unable to resolve indirections)

Top-down is in my experience less useful, because there are far too many choices on each level for most applications, and the first few layers are generally the least interesting and most arcane/fragile and difficult to follow along (things like initialization sequences).

The most difficult projects are typically those relying on multiple languages, code generation and runtime mutation (reflection, on-the-fly UI generation, overly dynamic Python code are typical examples). Another frequent obstacle is excessive abstraction and indirection (implementing something that could be done in a few lines of easy to understand and reason about C using multiple C++ templates spread out over a bunch of files and a healthy dozen of advanced language features is an almost archetypal example).

Use `tree | less` just to get an idea of where everything is and how it is structured and `tokei` to check out what the code actually is written in.

Then I try to go down the main code path of some examples or the primary binary if available and just check out out how things are called/done around there.

Then run an example through callgrind and visualize the call graph in kcachegrind to get an idea of how often things are called and where and where the heavy lifting happens. That last step is optional and really depends on the type of project.

Then I use my code editor and lots of searching and call site lookups to get a better idea of how things are used.

Go back to the first commit and work from there.