Ask HN: How do teams maintain understanding of large, long-lived codebases? | Hacker News Reader

Ask HN: How do teams maintain understanding of large, long-lived codebases?

I’ve been working on a tool called RepoDoc, focused on tracking and explaining how real codebases evolve.

What keeps coming up is that the hardest part isn’t generating docs or summaries. It’s preserving understanding as repositories grow in size, language mix, and history.

I’m curious how teams here handle this in practice.

Do you rely on conventions, internal tooling, documentation, or mostly social knowledge? What tends to break first as a codebase gets older?

View on HN

Strong HR practices to retain those who know it like the back of their hand

This is so essential.

Anything less is a very poor substitute at best.

IOW you can rake in the bucks a lot of other ways, outperform your wildest expectations and be perfectly satisfied financially, but you're really quite poor by comparison to how rich you would be if you did it right from the beginning.

Strong retention definitely helps, but even with good HR practices, long-lived systems inevitably outlast individual contributors.

What I’ve seen break first isn’t code correctness, but the loss of decision context, why the system looks the way it does today. That context usually lives in old PRs, commit messages, and informal conversations rather than in the code itself.

Documentation helps, but static docs decay quickly. Social knowledge helps, but it’s fragile. The hard problem is preserving intent and architectural reasoning as the code evolves, without slowing teams down.

I’m curious whether people have found practical ways to do that at scale.

>practical ways to do that at scale.

I know what you mean, the "HP Way" worked at scaling to the max but once Hewlett & Packard were no longer around it faded too.

Or crumbled or shattered, whichever way you want to look at it.

Maybe the "following generation" needs to actually work not only smarter but at least as hard as the founding generation.

And maybe that's less likely the more of the upside that's realized, things can get cushy and no-one may be able to focus on that kind of thing any more, especially after lots of time has obscured how much work it was to get big.

At least that's one thing I learned in the yachting community.

Reply on news.ycombinator.com