When I was a child, I spoke as a child, I understood as a child, I thought as a child: but when I became a man, I put away childish things.
— 1 Corinthians 13:11 KJV

It’s been pretty well understood, for a really long time, that adults, on average, know more than children. So nobody is surprised when a toddler doesn’t understand things.

This makes for a nice analogy when we’re early in our careers… we can easily accept that we have a child-like understanding to data structures, or compiler optimizations, or whatever. And that’s why the code we see doesn’t make sense to us.

But sooner or later (often as early as 6 months into your career as an engineer), you’ll start to see things that don’t make sense, and discover they came from someone with no more experience than you.

So “when I was a child, I understood as a child” no longer explains what’s going on.

What is going on?

Here’s the thing… life isn’t as simple as that. We all have different levels of understanding in different situations. In short: We all have a different context.

So when you come across some of my code and think “Gee, why the heck did he do that?” there are (at least) three possible explanations:

1. I (the code author) was the “child” in that situation. I had a lack of understanding, and your solution makes more sense.
2. You (the code reader) are the “child” in the situation. I, the author, had a stronger understanding, and you could learn something from me.
3. Neither of us are “children”, and we’re each responding to different contexts in which that code operates. My solution makes perfect sense for my context, but no sense at all for yours. Perhaps we need to work together to come up with a solution for both situations.

(Other possibilities obviously exist… such as the code has evolved slowly into a WTF state, but that’s for another discussion.)

So what can we do about this unfortunate ambiguity?

The only answer I know is to talk about it. We need to have a conversation about our two (or more?) contexts, to decide what makes sense. Together.

Of course, this is often impossible. The code you’re reading I may have written months or years ago, and I’ve moved on to a new company, been hit by a bus, or simply forgotten why I wrote the code that way.

So is hope lost?

Perhaps for that old code I wrote, it is.

But for new code, I can make an effort to document every decision I made, and the context in which that decision seemed to make sense. Code comments, clearly named variables, clear commit history, and links to bug numbers are a good start.