The Day I Couldn't Explain My Own Code

A simple question from my brother changed how I think about writing code

The Question I Couldn't Answer

It was a Tuesday afternoon when my brother asked to see what I'd been working on. He's not a programmer, but he's curious about tech, and I'd been excited to show him this data analysis tool I'd built.

"So what does this part do?" he asked, pointing at my screen.

The Code That Looked So Clever

I looked at the code he was indicating—a loop I'd written just three weeks earlier. It was supposed to process a list of customer records and extract some key metrics. I remembered being particularly pleased with how compact I'd made it.

results = [(c['name'], sum([p['amount'] for p in c['purchases'] 
          if p['date'] > cutoff and p['status'] == 'completed']), 
          len([p for p in c['purchases'] if p['date'] > cutoff])) 
          for c in customers if c['active']]

"Well," I started, "this takes each customer and..." I paused. "Actually, let me break this down. So we're filtering for active customers, then for each one we're calculating... um..."

I found myself pointing at different parts of the screen, trying to trace through the nested logic. My brother watched patiently as I stumbled through an explanation that involved multiple subclauses and conditions.

"So it's doing three things at once?" he asked.

"Well, yes, but they're related..." I trailed off, realizing how that sounded.

The Rewrite That Changed Everything

That night, I couldn't stop thinking about that moment. The code worked perfectly. It was efficient. It demonstrated that I knew how to use list comprehensions and nested logic. But I couldn't explain it to my own brother without getting tangled up in the syntax.

I opened the file and looked at that loop again. What if I had written it differently?

active_customers = []
for customer in customers:
    if customer['active']:
        active_customers.append(customer)

results = []
for customer in active_customers:
    name = customer['name']

    total_spent = 0
    total_purchases = 0

    for purchase in customer['purchases']:
        if purchase['date'] > cutoff:
            total_purchases += 1
            if purchase['status'] == 'completed':
                total_spent += purchase['amount']

    results.append((name, total_spent, total_purchases))

Suddenly, I could see exactly what the code was doing. First, find the active customers. Then, for each customer, look at their recent purchases. Count all recent purchases, but only sum up the completed ones. Simple.

The new version was longer, sure. But each line had a single, clear purpose. Each variable had a meaningful name. Each step followed logically from the previous one.

I imagined explaining this version to my brother. "First, we find customers who are still active. Then, for each active customer, we go through their purchases..." It would be a conversation, not a syntax puzzle.

What Code Is Really For

This wasn't about the list comprehension being wrong or right. It was about what code is really for. I'd been writing code to demonstrate that I could pack multiple operations into a single expression. But code isn't a compression algorithm—it's communication.

The next morning, I went through some of my other recent work. I found loops that tried to do too many things at once, variable names that made sense to me but would confuse anyone else, and clever shortcuts that saved lines but cost understanding.

I started rewriting. Not because the old code was broken, but because the new code was honest about what it was doing. Each function did one thing. Each variable had a name that explained its purpose. Each loop walked through its work step by step.

The Real Lesson

My brother probably forgot about our conversation within hours. But it changed how I think about programming. Every piece of code I write now gets an invisible test: could I explain this to someone who cares about the result but not the implementation?

The best code isn't the code that shows how much you know—it's the code that makes what you know accessible to others. Sometimes the most elegant solution is the one that doesn't require elegance to understand.

When I write loops now, I imagine I'm writing a recipe for someone else to follow. Each step should be clear. Each ingredient should be labeled. The person following the recipe shouldn't have to decode what I meant—they should be able to focus on what they're trying to accomplish.

It's funny how a simple question from a non-programmer taught me more about programming than years of trying to write clever code. The best code isn't impressive—it's clear. It doesn't show off—it shows up, does its job, and gets out of the way.

Now when people ask what my code does, I can actually tell them. And that feels like real progress.

---

Aaron Rose is a software engineer and technology writer at tech-reader.blog and the author of Think Like a Genius.