When “It Works” Isn’t Enough

I used to think that if my JavaScript ran without errors, I had done my job. If the feature shipped, the console stayed quiet, and the tests passed, I’d mentally roll for loot and move on. Victory secured. XP gained. On to the next quest. But somewhere between shipping features and revisiting old projects, I started noticing something uncomfortable: working code is not the same thing as readable code. And readable code is the difference between a clean campaign journal and a pile of crumpled notes written during combat.

One of the first times this hit me was with a small function that filtered active users and displayed their names in uppercase. Nothing dramatic. Just basic array manipulation. Here’s what I originally wrote:

const users = [
  { first: "John", last: "Doe", active: true },
  { first: "Jane", last: "Smith", active: false },
  { first: "Sara", last: "Connor", active: true }
];

let result = [];

for (let i = 0; i < users.length; i++) {
  if (users[i].active === true) {
    result.push(
      (users[i].first + " " + users[i].last).toUpperCase()
    );
  }
}

console.log(result);

It worked perfectly. It did exactly what it was supposed to do. But when I came back to it later, I had to mentally simulate the loop. Index. Check active. Concatenate names. Uppercase. Push. None of it was complex, but none of it was expressive either. The intent was buried under mechanics.

That was my first realization: code should communicate intent as clearly as possible. JavaScript gives us higher-level tools that allow us to write closer to the idea we’re expressing instead of the step-by-step plumbing required to get there. So I rewrote it like this:

const activeUserNames = users
  .filter(user => user.active)
  .map(user => `${user.first} ${user.last}`.toUpperCase());

console.log(activeUserNames);

Same behavior. Same output. But now it reads almost like a sentence. Take the users. Filter the active ones. Map them into uppercase full names. The structure mirrors the thought process. That’s the difference. It’s not about cleverness; it’s about clarity. And clarity is kindness – especially to the developer who inherits your code later. Sometimes that developer is you, three months from now, wondering why Past You made questionable life choices.

Another lesson that took me longer than I’d like to admit was about naming. In the first version, I used a variable called result. That name technically works, but it says nothing. Result of what? Refactoring often begins not with syntax changes but with better names. In the improved version, activeUserNames tells the whole story. Good variable names are like labeled drawers. When everything is named well, you don’t have to rummage around to figure out what’s inside.

I’ve seen the same pattern with more complex logic. I once wrote a function to calculate totals like this:

function getTotal(items) {
  let t = 0;
  for (let i = 0; i < items.length; i++) {
    if (items[i].price && items[i].quantity) {
      t += items[i].price * items[i].quantity;
    }
  }
  return t;
}

It worked. But the single-letter variable, the manual indexing, and the inline condition made it harder to parse than necessary. Refactoring it forced me to think about what the function was actually doing:

function calculateOrderTotal(items) {
  return items
    .filter(item => item.price && item.quantity)
    .reduce((total, item) => {
      return total + item.price * item.quantity;
    }, 0);
}

The logic didn’t change. The readability did. The function name explains its purpose. The parameters are descriptive. The flow mirrors the transformation of data instead of the mechanics of looping. When code reads this way, the cognitive load drops significantly. And lower cognitive load means fewer bugs hiding in shadowy corners.

Refactoring also changed how I handle conditionals. I used to stack conditions like bricks in a tower:

if (user.role === "admin" && user.active === true && user.loginAttempts < 3) {
  allowAccess();
}

Again, nothing technically wrong. But as those conditions grow, they become dense walls of logic. Refactoring meant extracting intent into a function:

function canAccessAdminPanel(user) {
  const isAdmin = user.role === "admin";
  const isActive = user.active;
  const hasValidLoginAttempts = user.loginAttempts < 3;

  return isAdmin && isActive && hasValidLoginAttempts;
}

if (canAccessAdminPanel(user)) {
  allowAccess();
}

Now the calling code reads clearly: if the user can access the admin panel, allow access. The messy details are tucked away behind a well-named function. In tabletop terms, the party doesn’t need to know every modifier behind the screen – they just need to know whether the door opens.

Another shift for me was embracing early returns. I used to nest conditionals like I was digging downward into progressively darker basements:

function processOrder(order) {
  if (order) {
    if (order.items && order.items.length > 0) {
      if (!order.isCancelled) {
        // process logic
      }
    }
  }
}

It worked, but the indentation told a story of creeping complexity. Refactoring with early exits flattened the structure:

function processOrder(order) {
  if (!order) return;
  if (!order.items || order.items.length === 0) return;
  if (order.isCancelled) return;

  // process logic
}

Suddenly, the main logic has room to breathe. The guard clauses clear away edge cases first, leaving the primary behavior visible and unobstructed. It’s like clearing out the low-level monsters before focusing on the boss encounter.

One subtle but powerful refactor I’ve learned to respect is eliminating magic numbers. I once had a condition like this:

if (user.score > 87) {
  grantReward(user);
}

Why 87? That number might make sense today, but six months from now it’s just a mysterious rune carved into stone. Refactoring it makes the meaning explicit:

const REWARD_THRESHOLD = 87;

if (user.score > REWARD_THRESHOLD) {
  grantReward(user);
}

Now the code explains itself. The number has context. Future changes become safer.

The biggest mindset shift for me was recognizing that code is communication. It’s not just instructions for a machine; it’s documentation for humans. If I need to explain what a function does in a long message to a teammate, that’s usually a sign the function needs refactoring. Good code answers questions before they’re asked. It signals its purpose. It reduces hesitation when someone needs to modify it.

I don’t refactor everything immediately. When I’m prototyping, speed matters more than elegance. But before merging, before shipping, before calling something “done,” I reread my code as if someone else wrote it. If I feel friction while reading it – if I have to pause and decode my own logic – that’s my cue.

Working code is the baseline. Readable code is professionalism. The best refactors don’t change what the program does; they change how confidently someone can understand it. They reduce mental strain. They make collaboration safer. They turn frantic combat notes into a clean campaign log.

And honestly, that’s the kind of upgrade that scales far beyond one function.