Skip to main content

Good software should explain itself.

August 10, 2026 Highland Software
Good software should explain itself.

In my previous article, Highland Principle #6: Code Is Read Far More Often Than It’s Written, I discussed an important truth of software development: you’re not writing code for the compiler, you’re writing it for the next developer.

That “next developer” might be a teammate.

It might be someone who joins the company years from now.

More often than not, it’s you six months later, trying to remember why you wrote a particular function.

Good software should explain itself.

Comments Are Not a Substitute for Good Code

I’m not suggesting comments are bad. Comments have their place.

Use comments to explain why something is done.

Don’t use them to explain what the code is doing.

Consider this simple loop:

for ($x = 0; $x < 10; $x++) {
    process_item();
}

It doesn’t need ten lines of comments explaining that the loop runs ten times. The code already tells us exactly what’s happening.

If you find yourself writing comments like this:

// Loop through ten items
for ($x = 0; $x < 10; $x++) {
    process_item();
}

the comment adds no value. It simply repeats what the code already says.

Poor Names Create Confusion

Now consider this function:

function get_id() {
    // Lookup code
}

At first glance, it seems straightforward.

But which ID?

Is it a user ID?

A customer ID?

A product ID?

An order ID?

A transaction ID?

Does your application only have one database table?

Probably not.

The function name forces every developer reading the code to stop and investigate what it actually returns.

Better Names Remove Questions

Now look at this instead:

function get_user_id() {
    // Lookup code

    return $user_id;
}

Immediately we know:

  • It returns a user ID.
  • It returns a single value.
  • The purpose is obvious.

Even better:

function get_user_id_by_email($user_email) {
    // Lookup code
}

Now there’s almost nothing left to guess.

The function name tells us:

  • what we’re retrieving,
  • how we’re finding it,
  • and what parameter it expects.

That’s self-documenting code.

Long Names Aren’t a Problem

One criticism I hear occasionally is:

“That function name is too long.”

I disagree.

I’d much rather read this:

get_user_id_by_email($user_email);

than this:

getId($x);

Saving a few keystrokes while writing the code isn’t worth the confusion every time someone has to read it.

Modern IDEs provide autocomplete, making longer function names almost effortless to use. The extra clarity far outweighs the small increase in typing.

Variables Matter Too

The same principle applies to variables.

Compare:

$x = get_user_id($email);

with

$user_id = get_user_id($email);

Which one tells you what’s happening?

Or consider:

$data = get_customer_orders($customer_id);

versus

$customer_orders = get_customer_orders($customer_id);

The second example makes the code easier to understand without requiring a single comment.

Write for the Reader

Every unnecessary question your code creates slows someone down.

What does this function return?

What is this variable?

What does $x represent?

Which ID is this?

Every one of those questions is an opportunity for confusion or bugs.

Clear naming removes those questions before they’re ever asked.

Final Thoughts

Good software shouldn’t require someone to reverse-engineer your intentions.

It should communicate them naturally through clear structure, descriptive function names, meaningful variables, and simple, readable logic.

Yes, your function names might become longer.

Yes, your variables might be more descriptive.

But when it’s time to debug an issue six months from now—or when another developer inherits your code—you’ll both be grateful that the software explains itself.

Because good software doesn’t just execute correctly.

It communicates clearly.

Highland Principle #7: Good Software Should Explain Itself

More From Highland Software