I’m working with someone to fix a bug in some code. I want him to be able to actually do the fix, and in the process, learn more about the code base. He’s taking over a project from me that I’ve been working on in isolation for a year or so, so the priority is on shifting the knowledge from my head to his rather than immediately fixing the bug.
I think I have a fix (which I developed in the process of trying to explain the code), but just handing it over wouldn’t achieve the goal of giving him the deeper understanding of the code that he needs going forward (I still offered him the option; we’ll see what he thinks). The fix only affects about three lines of code, and it probably would have taken me about 45 minutes to find and fix myself. But explaining the whole context of the code, and precisely how it was that I screwed up in the first place, that’s a lot more work. I spent 3 hours trying to document the meaning of one relevant variable, and I still feel like I didn’t do a great job of it. It will be at least another couple hours of work to describe exactly how I fixed the bug, if he wants to hear it.
This might be one of those cases where he’d be better off refactoring the code. Sometimes people use refactoring as a way to gain deeper understanding of the code, as well as making it easier to understand in the future. In this case, for example, I wrote a function called adjust-rowspan-vec, which probably should have been named update-rowspan-vec-for-next-row. Though the name rowspan-vec in itself is not all that clear, but ugh, it’s hard to find a good name for that one; maybe data-for-cells-which-span-rows-and-are-currently-in-flight-so-that-we-can-track-where-to-insert-dummy-cells-as-we-scan-down-the-input-rows, or something. So, yeah, probably needs a refactoring, just so that we can better wrap our heads around whatever concept I was trying to express with rowspan-vec.
It’s hard to describe the concepts in use in the code even if it was working properly, but to describe my partially-broken mental model when I wrote the incorrect code would add another level of complexity. I think I could do it, though, and it’s awesome that human languages have the ability to express such deep weirdness.
[And just to vent a little more, none of this is made any easier by the fact that the code in question is in a functional language, which means we’re using immutable variables and two levels of recursion rather than mutable variables and loops. Nor is it made easier by my lack of confidence in communicating in English with someone whose first language is not English…]
One comment