Ask HN: Working with large code base for the first time

For classic backend server software, for years I found the best way in was to look at the database schema, to understand those relationships, and then to see how the software itself was segmented (or not) in its relationship with the different parts of the database. If it was easy to understand the segments, and their relationship to the database, then I could assume that the software had good module interfaces with clean separation, but if every module was a mix using data from the same database tables, then I assumed I was dealing with a problematic code base that lacked good clean interfaces.

When dealing with frontend code, my attitude remained the same, but instead of looking at the database, I'm typically looking at the API. The goal is to see how data flows through the app. That is certainly one way, for understanding the code. This used to be easier, with classic RESTful APIs, I find this approach is a bit more difficult when using GraphQL.

Also, just to state the obvious, run the unit tests. If the code base lacks good test coverage, ask if you can start there, writing more tests -- that will give you a purpose and a structured way of diving into the code. I also suggest that you deliberately break things, and then see which tests fail -- if a test fails and you weren't expecting it to fail, then you just discovered a linkage in the code that you didn't think would be there.

As someone who has worked for years on a UI consuming such information: it's bloody difficult. Each language has its own weirdnesses, you almost always have to build the code to figure out the cross references, and what's correct to the compiler is often non-intuitive to the user. Prime example: C++ code mixing macros and templates. There isn't even a good definition of what the definition is!

Ask, ask, ask. Yes, you can spend days or weeks poring over the code in various ways, but asking those who made it (ideally) or those who maintain it will give you the "why". Why was it done this way? What are the implicit assumptions and invariants? Why were seemingly obvious ideas not implemented? Or were they and found problematic? Document these findings for the next generation.

But as you do this, keep an eye out for assumptions that may have changed. A feature now obsolete requiring weird code. Out-of-date assumptions about the behaviour of computers or other systems. New language features that can simplify or improve code. Talk them over with the people who know the code, and maybe you'll be the one to delete that awful code everyone hated.

Also, take notes, not just about the code, but about its environment, release process, surrounding systems, use cases, and people. Knowing who to ask about a given issue is gold.

If there are post-mortems available, they can give a great insight into how the system works and fails. Design docs to a certain extent, too, but they can be misleading especially if they are not kept up to date.

Pair programming can be a very effective way of learning, too.

I'm a firm believer that the onus should be on the current development team to explain this to you. That is unlikely IME to happen without you asking.

What happens next will be an iterative process.

Do some initial investigation - don't waste time figuring things out, we just want a set of questions and areas to explain at this stage.

Ask for some help from the team - perhaps 30-60 mins, perhaps with different people to cover off the topics. It's essential that the team contribute - firstly they owe it to you, secondly only they know the background. Which bits of the codebase were experimental, which bits are ancient relics being removed, what's the direction of travel, which parts have subtleties. "Unknown unknowns" (to you).

Now "pay it forward". Ensure that the next person to join the team has a better time. Maybe this is writing some documentation - be it architectural, a glossary of domain-specific terms, updating/culling outdated docs. Maybe parts of the codebase could do with some re-organising or renaming to make it more self-evident. Perhaps the build/test process could do with some care...

I've done this several times, and after 3-4 hour sessions with "the one person who understands" (and a few hours writeup), we now have good documentation, better standards and multiple people including new joiners who understand. The guru also appreciates having more people to bounce ideas around with and no longer being overloaded with this work.

Realistically, i agree with your point and it's probably a good course of action!

> Ask, ask, ask. Yes, you can spend days or weeks poring over the code in various ways, but asking those who made it (ideally) or those who maintain it will give you the "why".

My question, however, is why aren't these things documented in the first place? In DevTernity (a recent software development conference), the concept of ADRs (https://adr.github.io/) was discussed. To me, it made a lot of sense: the code is the implementation, whereas a bunch of Markdown files can explain the "why" behind it, as well as all of the stuff that wouldn't appear in Jira or regular code comments or wherever.

After all, not every senior dev has that many hours to spend onboarding new team members, nor are their memories also that good to remember everything.