by Serguey Shinder
I had inherited a scheduling component nobody had touched in four years, and I needed to change one thing inside it without breaking the rest. It was about nine hundred lines, written by someone who had left, in a style that was consistent and unfamiliar. So I did what has become normal and asked a model to explain it to me.
The explanation was excellent. Clear structure, plain language, a walkthrough of the main path with the edge cases called out at the end. It was better written than anything I would have produced after an hour with the file, and I read it twice and felt the specific relief of a hard thing becoming an easy thing.
Then I made my change, and it did not behave the way the explanation said it should.
The summary had been mostly right, which is the part worth dwelling on. It got the structure right, the entry points right, the general shape of the flow right. What it got wrong was one branch that only ran when a particular field was absent, and in that branch the component did something almost opposite to its normal behaviour. Reading the code, you would have noticed, because the branch is right there and it is strange enough to stop on. Reading a clean summary, you would not, because a clean summary is exactly the thing that makes strangeness disappear.
That is what I had actually bought. Not understanding. Coherence. The two feel identical from the inside, which is why I went straight from reading to editing without the hesitation I would normally carry into a file that old.
What made it worse is that I had a story now. When the behaviour surprised me, my first instinct was not that my mental model was wrong, it was that something else in the system must be interfering, because the model of the component in my head was clear and confident and had come to me pre-organised. I spent a while looking in the wrong places, defending a picture I had not built and whose weak points I did not know.
I have not stopped asking for explanations. They are genuinely useful for orientation, for knowing where to start, for turning nine hundred unfamiliar lines into a map with some names on it. What I have changed is what I do next. I now read the code before I change it, specifically hunting for the parts the summary did not mention, because the omissions are the whole risk and they are invisible by construction.
The uncomfortable version of the lesson is this. When I read code badly, I know I have read it badly. When something reads it for me and reads it well, I get all the confidence of having understood it and none of the understanding, and nothing about the experience warns me which one I have.
– Serguey Asael Shinder
Leave a Reply