Like a Jedi Master: Code Review Best Practices That Actually Improve Code Quality

The Quest Begins (The "Why")

I still remember my first big pull request at a startup. I’d spent the weekend building a feature that let users export their reports as PDFs. I felt like a hero — until the review comments started rolling in.

“What does tmp hold here?”

“Why are you looping twice?”

“Can you add a comment explaining this calculation?”

I stared at the screen, feeling like I’d just been handed a riddle written in ancient runes. The code worked, sure, but it was a nightmare for anyone else to read. I spent hours defending choices that seemed obvious to me, only to realize later that the real problem wasn’t my logic — it was how I’d expressed it.

That moment was my “aha!”: if I wanted my code to survive review (and live beyond my own brain), I needed to change how I wrote it, not just how I defended it.

The Revelation (The Insight)

The single practice that transformed my approach was writing intention‑revealing names — for variables, functions, classes, everything. It sounds trivial, but treating every identifier as a tiny piece of documentation forces you to think about the why before you type the how.

When a name tells the reader exactly what a thing does, the need for explanatory comments drops, reviewers can spot logic errors faster, and future you (or a teammate) won’t need to decode hieroglyphs.

Think of it like a lightsaber: the blade does the cutting, but the hilt’s shape tells you how to grip it safely. A good name is that hilt — it gives you control without you having to think about it.

Wielding the Power (Code & Examples)

The Struggle – Vague Names

Here’s a snippet from that PDF‑export feature before I embraced the naming habit. I’d thrown together a quick helper to compute the total price of line items:

function calc(a, b, c) {
  let sum = 0;
  for (let i = 0; i < a.length; i++) {
    sum += a[i] * b;
  }
  return sum * (1 - c);
}

What’s happening?

• a – an array of quantities?
• b – a unit price?
• c – a discount rate?

Even after reading the function a few times, I had to pause and trace the logic. During review, a colleague asked, “Why are we multiplying by b inside the loop?” I explained, but the fact that the question existed at all meant the code wasn’t speaking for itself.

The Victory – Intention‑Revealing Names

After I made naming a first‑class concern, the same logic became:

function calculateTotalPrice(itemQuantities, unitPrice, discountRate) {
  let total = 0;
  for (let i = 0; i < itemQuantities.length; i++) {
    total += itemQuantities[i] * unitPrice;
  }
  return total * (1 - discountRate);
}

Now the purpose is obvious at a glance:

• We’re summing the price of each item (quantity * unitPrice).
• Then we apply a discount (* (1 - discountRate)).

No extra comment needed. When a reviewer sees calculateTotalPrice, they instantly know the function’s responsibility and can focus on whether the algorithm is correct, not what the variables mean.

The Trap – Over‑Abbreviating

A common pitfall I still see (and have fallen into) is trying to be “clever” with abbreviations to save a few characters:

function getUsrData(id) {
  const usr = db.fetch(id);
  return usr.name + ' ' + usr.email;
}

What does usr stand for? User? Usuario? Unspecified Resource? The reviewer has to guess, and the guess might be wrong. The fix? Spell it out:

function getUserData(userId) {
  const user = db.fetch(userId);
  return `${user.name} ${user.email}`;
}

The extra five characters save minutes of confusion later — time that could be spent shipping features instead of deciphering code.

Why This New Power Matters

Adopting intention‑revealing names changed my workflow in three concrete ways:

1. Reviews became dialogues about logic, not semantics. Instead of answering “what does x mean?”, we could dive straight into edge cases and performance.
2. Bugs dropped. When the code reads like a sentence, it’s harder to write a mistaken assumption — e.g., mixing up quantity and price because the names forced you to keep them separate.
3. Onboarding sped up. New teammates could skim a file and grasp the domain model without needing a senior dev to walk them through every line.

It’s like upgrading from a foggy windshield to a clear one: you still have to steer, but you can see the road ahead.

The Challenge – Your Turn

Give it a try on your next piece of code. Pick a function or variable you’ve been tempted to name data, tmp, info, or something similarly vague. Rename it so that a stranger could guess its purpose just by reading the identifier. Then, drop the snippet in a PR and watch how the conversation shifts.

When you feel that moment of clarity — when the code speaks for itself — let me know in the comments. I’d love to hear how this simple habit leveled up your coding quest.

May your names be ever expressive, and your reviews ever productive! 🚀