> Patching that up by using comments as a 'map' isn't the right way to deal with that.

There is no right way. Only grey ones that help relieve pain for the team.

> Refactors and rearchitecture are.

Yeah... if you have the cash and the people. Usually, mature codebases are driven by limited investment with proven business value, because the sweet VC money is no longer there (or never was, in some industries).

If you don't, reachitecturing is vanishingly rare, and your refactor budget is limited and you spend it carefully. If a piece of code hasn't moved recently but still comes up frequently when onboarding newcomers, documenting the code may be more profitable and less risky than changing it. It also helps preparing a case for a potential refactor.

Rewrites require a lot of effort, significantly more than just adding comments. It’s a pragmatic tool until you actually have the time to do the rewrite.

It's difficult to refactor and rearchitect without first understanding what's there and why.