Defining Good Code

“It is tempting to linger in this moment, while every possibility still exists. But unless they are collapsed by an observer, they will never be more than possibilities.” - Solanum, Outer Wilds

Good code. I would begin with a definition if there was one to be had. Software engineers, scientists, hobbyists, and developers of all backgrounds have argued over what constitutes good code since the era of the punch card. Countless folks have written down their thoughts on what makes code good, now it is my turn. What follows is a biased opinion of code quality from the perspective of someone who develops scientific research software.

Correctness

It is a low bar, but perhaps the only one universally agreed upon: good code works. As scientists we can be more precise about what it means for code to work. The process for checking code correctness is known as Validation and Verification.

Validation:

Is the physical model correct? Are we solving the right equations for the scenarios that we wish to simulate?

Example: A diffusive model for radiation transport is incorrect in the optically thin limit and cannot capture shadows.
Verification:

Are we solving the equations correctly?

Example: Does our second order finite volume method converge at second order?

Good scientific software is both validated and verified.

Readability

Code is more often read than it is written. There is a common saying that gets the point across succinctly:

“Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live. Code for readability.” - Origin unclear

That psychopath could be a future user of your code or even yourself in a year. Good code communicates intent. This is deeper than just commenting your code (which you should do!) and touches on variable naming, organization, control flow, and scope. The goal is to minimize cognitive load on the reader. The more information that a reader must keep in their mental cache the less likely it is to be understood, the easier it is to break, and the harder it is to maintain.

Maintainability

Closely related is the idea of maintainnability. We want our software to stick around into the future. Often it lasts longer than we expect. As time marches on, new physics gets added, boundary conditions evolve, hardware constraints shift. Good code anticipates this, minimizing barriers to extension. This rests on readability, clear documentation, and well-managed and thought out dependencies.

When writing code I try to adhere to the following approach:

“First make it work, then make it beautiful, and only if you need to, make it fast.” - Jose Valim, creator of Elixir

In practice, this progression enforces everything above: correctness first, clarity second, and performance where it matters. Good code works—but more importantly, it can be understood, trusted, and changed.