How do folk keep mental models of code up to date as you review work on an area? I’ve had the classic “start a project as a more senior engineer and then incrementally hand it off to a more junior engineer” situation, and after being mostly out of making changes to the code myself and only doing code review for it, it’s been rather difficult to keep all the semantics straight in my head as new features and bug fixes are landed. This was easier when I was more junior, and handing off some piece of work meant I still stayed relatively nearby, but as I’ve gotten more senior and hand off projects to more senior people, it’s a larger scope being handed off, and so my own core work ends up further away. Does everyone just struggle with this? Are there some reasonable strategies for trying to deal with this? I’ve been considering trying to maintain a “mental model” doc, that’s just a list of semantics, system behavior, and weird edge cases…
I hear ya. Still learning this myself.
1-1s with folks “on the ground” are helpful here, and asking insightful questions. Nothing beats digging into the code yourself every so often.
PR reviews are also a great place to ask questions.
But I think it’s ultimately healthy to start to drift further from the “core.” For example, my role recently was more to ensure the teams were setup for success, had great context and could make optimal trade off decisions “on the ground.”
Would love to hear what works for you!
Yeah, same, I experience the same problems and haven’t found a great solution, either
Maybe documentation of that nature is not manageable at scale, as in scaling with number of devs, new and changing project proposals, commit PRs, etc.
One take is that code quality is self documenting. Ideally the architecture is clear enough that responsibilities are separated in distinct, declarative modules and services, where a brief description and explanations on specific capacities are enough to understand most of what’s happening.
I’m much more confident that modular decomposition is the best way to understand the architecture of a program/system, cutting down the necessary documentation to be relatively sparse. The common attempt of endless amounts of documentation seems to be a bandaid to obfuscated design.
The replies here and those I’ve collected around suggest that maybe I’ve painted a bit of a mistaken picture. I haven’t ascended into management or multiple levels far away, I’m just a staff engineer stuck in the trouble that I’ve handed off a project to a senior engineer, but in my staff+ responsibility of collaborating with neighboring teams and projects, I’m still in a situation where knowing the handed off system in detail is still something that is expected of me in some situations. I’m still reviewing the majority of the code that’s committed against the system, but we’re talking over a span of a few years now. Even as I’ve increasingly deferred direct questions about “how does XYZ work in Handed Off System?“, there’s still a good number of conversations that I get pulled in for where it’s like “hey, here’s my design for Neighboring System Improvement, could you please take a look?” because there’s tie ins to things I’ve been responsible for. Sometimes these even come from the senior engineer now owning the project and doing other related work as a “hey, could you double check I didn’t miss anything?“.
A good chunk of these are answerable with the decent mental model of the system that I have, but then sometimes the correct answer is more like “99% of the time it’s ABC, but 1% of the time this weird thing can happen where XYZ”, but then I end up confusing a conversation that we had a year ago about a potential change with actual implemented system behavior, or forgetting how this one weird edge case got resolved, or misremembering what the rules were for this complicated bundle of dragons that took a number of hairy fixes sometime back, etc. Most of this is solvable by going back to the code for a while, but then I’m left doing a code study to double check a decent amount of what I say. Which, maybe if I did that more often, then it’d be faster and my memory would be better?
Or maybe I just need to accept that my memory will now be sketchy, and it just feels weird because having implemented the majority of what was there before, my accuracy for answers used to be near 100% ¯_(ツ)_/¯
