I was digging into a new client’s WooCommerce site last week. They had a custom filtering system for product certifications, things like ‘Organic’ and ‘Fair Trade.’ But it was buggy as hell, and simple filtering was timing out. The previous developer’s code was a maze of variables like $p_meta, $cert_arr, and functions called get_stuff(). It took me longer to work out what the code was supposed to do than to actually fix the bug.
This is where clear variable naming stops being academic and turns practical. It’s the difference between a five-minute fix and a two-hour archeological dig through someone else’s brain droppings. Bad naming costs clients real money.
Your code should tell a story
My first impulse was to patch the broken logic: find the one conditional causing the timeout, fix it, and move on. That would have worked for now. But I’d be leaving a time bomb for the next developer, or worse, for future me six months from now.
The real problem wasn’t the bug, it was the ambiguity. What was in $cert_arr? An array of post IDs? Term objects? A mix? The name tells you nothing. And you can’t lean on comments to save you, because they tend to be wrong, outdated, or just restating the obvious. The code itself should be the source of truth.
// What does this even do?
function process_data($data, $type) {
$results = [];
foreach ($data as $d) {
if ($d->status == 'active' && $d->type === $type) {
$results[] = $d->id;
}
}
return $results;
}
// Ah, that's much clearer.
function get_active_product_ids_by_certification($products, $certification_slug) {
$matching_product_ids = [];
foreach ($products as $product) {
if ($product->post_status == 'publish' && has_term($certification_slug, 'p_certification', $product->ID)) {
$matching_product_ids[] = $product->ID;
}
}
return $matching_product_ids;
}See the difference? The second function doesn’t need a comment. You know exactly what it does from the function name and the variables inside it. It’s self-documenting. That’s what professionals do: we write code for humans first and computers second. This idea builds on something I read years ago over at carlalexander.ca, where the author describes creating a “ubiquitous language” that everyone on a project can understand.
So what’s the takeaway?
Really it comes down to empathy, not some arbitrary style guide. You’re writing code that other people have to read, debug, and maintain, so don’t make their job harder to save yourself a few seconds of typing. Naming things properly is a sign of a senior developer who respects their colleagues and their clients’ time.
- Name variables and functions for what they are or do. Be explicit.
- Avoid abbreviations. Is
$cata category, a catalog, or a feline? Don’t make people guess. - If a function is hard to name, it’s probably doing too much. Break it down.
This stuff gets complicated fast. If you’re tired of debugging someone else’s mess and just want your site to work, drop my team a line. We’ve probably seen it before.
