The code that should stay

Code that:

• Works
• Has tests
• Nobody complains about
• Is not on the critical path

Leave it. A refactor is not free—it is a bet that the improvement is worth the
risk.

The code that needs refactoring

Code that:

• Works but is hard to change
• Has been changed three times already
• Everyone dreads touching

This code is expensive. Every change costs more than it should. Refactoring
pays for itself in the next change.

The refactor that goes wrong

A function that is confusing, so you refactor it to be clear. In the process,
you change the logic slightly. The tests still pass because the tests were
written to test the function, not to test the behavior.

The refactor changed the behavior and the tests did not catch it.

The safe refactor

Tests first. Run them. Change the code. Run them again. If they pass, the
behavior did not change.

If the tests do not pass, the refactor changed something and the change is
detected.

What I learned the hard way

A refactor without tests is not a refactor, it is a rewrite. Rewrites introduce
bugs. Refactors do not.

The question that matters

“Will this refactor make the next change easier?” If yes, do it. If no, the
code is fine the way it is.

The code that is hard to read but easy to change is better code than the code
that is nice to read but hard to change.

The purpose of refactoring is not beauty. It is to make future changes
cheaper. If there will be no future changes, there is nothing to refactor.

The test that passes but the code is wrong

def eligible_for_discount?(purchase_amount)
  purchase_amount > 100
end

Test:

assert eligible_for_discount?(101)
assert !eligible_for_discount?(100)
assert !eligible_for_discount?(99)

All pass. The code is wrong. The rule is “greater than or equal to 100” not
“greater than 100.”

The test writer and the code writer made the same mistake. The test
confirmed the mistake.

What a review finds

A human reading the code asks: “What if the amount is exactly 100?” and finds
the boundary is wrong.

The logic that is technically correct but practically wrong

def refund_request_days_remaining(purchase_date)
  days_since = (Date.today - purchase_date).to_i
  30 - days_since
end

The test passes. The code is correct. But if a customer bought on day 0, they
have 30 days. If they bought on day 1, they have 29 days. If they bought on day
30, they have 0 days.

The business rule is probably “within 30 days of purchase,” which means day 30
should have 1 day remaining, not 0.

A test can confirm the calculation. Only a human can catch the off-by-one
business logic.

The performance that is not tested

def find_active_users
  User.all.select { |u| u.active? }
end

The test passes. The code is correct. With 100 users the query is fast. With
100,000 users it is a DOS attack waiting to happen.

A test cannot measure intent. A human can ask: “What happens when this table
grows?”

Why this matters

Tests confirm the implementation. Reviews confirm the intention.

A reviewed test suite is one where the code does what you meant and does it
efficiently.

An untested review is one where clever code breaks in production. A tested
review is one where clever code fails fast and obviously.

The review that asks “Is this right?” catches the bug. The test that asks
“Does this work?” catches the typo. Both are needed.

The correction

“The function is too long. Split it into two functions.”

This is correct. It is also lazy. The author learns nothing except that the
reviewer does not like long functions.

The lesson

“This function does three things: parse, validate, and persist. Each of these
is a decision point. When the parsing fails, someone reading this wants to know
whether the validation failed or the persistence failed. Right now they cannot
tell. Split it into three functions so the failure point is clear.”

This teaches why. The author learns that the reason to split is not fashion,
it is clarity. The next time they write a function that does multiple things,
they will make the decision themselves.

The comment that changes code

“What happens if user.name is nil?” turns into a check, a test, a fallback,
and the code is more resilient.

“This will crash if the user has no name” teaches why it is a problem.

What reviewers often do wrong

1. Correct the code without explaining the reasoning
2. Suggest a fix without explaining the trade-offs
3. Approve code that works but will be hard to maintain
4. Disapprove code that is a little different from how they would have written it

What reviewers should do

1. Explain the reasoning: “This pattern makes it easier to test because…”
2. Explain the trade-off: “This is slower but it is clearer…”
3. Ask the question: “What happens if this fails?”
4. Differentiate: “I would have written it this way, but your way is fine too.”

The review I am most proud of

A function was correct but confusing. I wrote: “I do not understand what this
function does from reading the name or the code. Can you rename the function
and add a comment about the three cases you are handling?”

The author rewrote it in twenty minutes and asked: “Is this better?” It was. And
they learned that clarity matters more than correctness.

Why this matters

A junior developer reading a correction learns that they made a mistake. A junior
developer reading a lesson learns how to make better decisions.

The review that teaches is the one that stays with someone for years. The
review that corrects is forgotten by tomorrow.

The name that lies

def process(data)
  parse(data)
  validate(data)
  save(data)
end

What does this do? No idea. process could mean anything. Six months from now,
someone reading this will spend twenty minutes figuring out what it does.

Better: import_and_validate_user_data or parse_and_persist_csv or whatever
it actually does.

The name that tells a story

def apply_late_fee(invoice)
  invoice.amount += 10
  invoice.save
end

The name tells a story: this function applies a fee. The code confirms it: the
amount increases and the change is persisted.

The name and the code agree, and someone reading the name knows what to expect.

The name that hides the cost

def get_user(id)
  User.find(id)  # database call, 50ms
end

The name says get. The reader expects a cache lookup. The code does a
database call. The name is not lying but it is misleading.

Better: fetch_user_from_database or load_user or something that hints at
the cost.

The rule that works

A name should answer the question: “What happens if I call this?” If the name
does not answer that question, the name is wrong.

The name that is technically right but still wrong

def handle_response(response)
  # 200 lines of logic
end

Technically correct. But the word handle is so broad that it is empty. It does
not answer the question at all.

The names in every codebase

• utils, helpers, common — names that mean nothing
• process, handle, do_something — names that tell you nothing
• temp, obj, x — names that tell you the author was hurrying

These names are not bad because they are short. They are bad because they do
not answer the question.

What I learned

Spend more time on the name than the code. A name that is right makes the code
obvious. Code that is obvious is easier to maintain.

The name that costs you five minutes to think of saves someone an hour of
confusion later.

What the test misses

def charge_account(amount)
  balance = get_balance
  if balance > amount
    deduct(amount)
    log("charged", amount)
  else
    log("declined", amount)
  end
end

The test passes. Balance is sufficient, charge succeeds, log is called. All
green.

The review finds: if balance is exactly equal to amount, nothing happens. The
code is written as > not >=. The test did not catch this because the test
writer assumed the same condition as the author.

What a human finds

1. A condition that is stricter than intended
2. A variable name that could be clearer
3. An assumption that might not be true in edge cases
4. A log call in both branches that could be factored out

Tests find that the code runs. Reviews find that the code makes sense.

Why both matter

A tested untested code breaks. A reviewed tested code might be slow, might
be wrong in a way the test does not check, might be a footgun waiting to
surprise someone.

The test that misses the review

def send_email(address)
  if valid_email?(address)
    email_service.send(address, template)
  end
end

Tests pass for valid emails and invalid emails. The review finds: what if the
email service fails? What if the template is missing? What if valid_email?
returns true for something that is not actually valid?

The review that finds the bug the test could not

A test cannot know what you did not test for. A review can ask the question:
“What happens if this breaks?” and “Are we ready for that?”

Why this matters

Code review is not about correctness. It is about resilience. A function that
works is not a function that continues to work when something changes.

The review is where you ask whether the code is ready for the future. The
test is where you confirm it works today.