Code Is Read Far More Often Than It’s Written

Building upon what was discussed in a previous article, https://highland-software.com/build-for-the-next-developer-not-just-yourself/, we further discuss the need for clean code.

“The compiler only needs correct syntax. The next developer needs understanding.”

One sentence has influenced the way I write software more than almost any other:

Code is read far more often than it’s written.

Every developer knows this.

Surprisingly few develop like it’s true.

A function might take five minutes to write.

A bug investigation six months later might involve reading that same function dozens of times.

A new developer joining the project might spend hours trying to understand it before making a single change.

A future enhancement might require tracing its behavior through multiple classes, services, and database calls.

The original act of writing the code is often the smallest part of its lifecycle.

Reading it is where the real cost lives.

And that cost compounds for as long as the software exists.

We Don’t Write Code For The Compiler

One of the biggest misconceptions in software development is believing we’re writing code for the compiler, interpreter, or runtime.

We’re not.

The compiler doesn’t care whether your variables have meaningful names.

It doesn’t care whether your methods explain their purpose.

It doesn’t care whether your architecture is intuitive.

The compiler only needs valid syntax.

People need understanding.

Those are very different requirements.

Consider these two examples:

public function get_name(
    int $id
): string {

    ...
}

and:

public function get_school_board_name_by_id(
    int $school_board_id
): string {

    ...
}

Both functions might produce identical output.

Only one explains itself.

The second version answers several questions immediately:

• What is being returned?
• What identifier is being supplied?
• What type of object is being queried?
• What relationship exists between the parameter and the result?

No documentation required.

No walkthrough meeting required.

No Slack message asking another developer for clarification.

The code explains itself.

That’s valuable.

Ambiguity Is Expensive

One thing experience teaches very quickly is that ambiguity has a cost.

Consider this:

$name =
    get_name(
        $id
    );

What does this return?

A school board name?

A user name?

A client name?

A department name?

A project name?

Without additional context, we don’t know.

Now compare it to:

$school_board_name =
    get_school_board_name_by_id(
        $school_board_id
    );

The purpose is immediately obvious.

The variable explains the data.

The method explains the operation.

The parameter explains the input.

A developer reading that code six months later doesn’t need to investigate further.

And that matters because developer time is expensive.

Every minute spent understanding unclear code is a minute not spent delivering value.

Variables Should Describe What They Contain

Variable names are one of the easiest places to improve readability.

This:

$x = get_location();

tells me almost nothing.

This:

$user_location_id =
    get_user_location_id();

tells me considerably more.

Likewise:

$intUserLocation

immediately communicates intent.

The variable appears to:

• contain an integer,
• represent a user location,
• likely reference another entity,
• possibly relate to a lookup table.

Even if some developers dislike Hungarian notation, the principle remains valid:

Variable names should communicate meaning.

Because meaning is what future developers are searching for.

Context Matters

There are exceptions, of course.

Not every variable requires a twenty-character identifier.

This is perfectly reasonable:

for (
    $i = 0;
    $i < $count;
    $i++
) {
    ...
}

The scope is small.

The purpose is obvious.

The context provides meaning.

But this:

process(
    $x,
    $y,
    $z
);

inside a business-critical workflow is very different.

What are we processing?

What do those values represent?

What units are they using?

What assumptions exist?

Single-letter variables outside of very small scopes often create confusion rather than reducing complexity.

Comments Should Explain Why, Not What

Comments are important.

Bad comments are not.

One of my least favourite examples is:

$i++;

followed by:

// Increment counter

The comment adds no value.

The code already explained itself.

Good comments explain decisions.

For example:

/*
--------------------------------------------------
WSIB requires claim identifiers to remain stable
between imports, even if the source system
renumbers records.
--------------------------------------------------
*/

That comment provides context.

It explains why the code exists.

Without it, a future developer might remove the logic during refactoring because it appears unnecessary.

The code explains the implementation.

The comment explains the decision.

Those are very different responsibilities.

Documentation Is For Systems

Code comments solve local problems.

Documentation solves system problems.

Good documentation answers questions like:

• Why was this architecture chosen?
• What external systems are integrated?
• What assumptions exist?
• What dependencies are critical?
• What deployment steps are required?

A developer shouldn’t need to reverse engineer an entire application to understand how it fits together.

The easier software is to understand, the cheaper it becomes to maintain.

Clever Code Ages Poorly

Early in my career I was impressed by clever solutions.

Dense one-line expressions.

Complex regular expressions.

Nested ternary operators.

Magic.

Now they mostly make me nervous.

Because clever code often optimizes for the person writing it rather than the person reading it.

Readable code scales.

Clever code requires explanation.

And software that requires explanation eventually becomes expensive software.

The best code often feels almost boring.

That’s usually a compliment.

The Original Developer Won’t Always Be There

Every developer eventually leaves a project.

Sometimes another team takes ownership.

Sometimes a client changes vendors.

Sometimes you become the next developer inheriting your own work six months later.

Future you is still another developer.

Code that seemed obvious during implementation rarely feels obvious years later.

We’ve all experienced opening an old project and wondering:

Why did I do this?

Good naming reduces that problem considerably.

Good documentation reduces it further.

Good architecture reduces it even more.

Maintainability Is A Feature

Clients rarely ask for maintainability.

They ask for outcomes.

A faster website.

Better reporting.

Improved workflows.

New functionality.

But maintainability affects every one of those things.

Features are easier to add.

Bugs are easier to fix.

Developers become productive faster.

Technical debt accumulates more slowly.

Maintainability may not appear in a feature list.

But every project benefits from it.

Write For The Reader

One of the biggest changes in my thinking over the years has been realizing that software isn’t written once.

It’s read repeatedly.

By developers.

By testers.

By support teams.

By future consultants.

By your future self.

Every decision should make that experience easier.

Choose descriptive names.

Organize files logically.

Prefer clarity over cleverness.

Write comments that explain decisions.

Document architecture.

Make intent obvious.

Because the compiler only needs code that works.

The next developer needs code they can understand.

And one day that next developer might be you.

Final Thoughts

Good software should never depend on the original developer being available to explain it.

Variables should describe what they contain.

Functions should describe what they do.

Comments should explain why decisions were made.

Documentation should explain how systems fit together.

Because code is read far more often than it’s written.

And every minute another developer spends understanding your code is a minute they aren’t spending improving it.

Make their job easier.

They’ll probably return the favour someday.

Highland Principle #6: Code is read far more often than it’s written. Write for the reader, not the compiler.