Friday, December 30, 2022

Understability of code should be the default priority

All things being equal, so not when performance is an issue, and in addition to any existing coding conventions, the understandability of code is the most important thing.

Typically this means, "can I read the and easily understand 'everything' about it?"

In the past, I've said that "readability" is the most important thing but what I've realized lately is that I mean: can I easily read it AND understand it?

This is more important than "SOLID principles" or "Clean Code."

Delivering value is the end goal when writing code. The code is a means to an end. It's not an end on its own. The primary goal is not to have code that meets a specific standard. Even if there are appreciable benefits from following that standard. The goal is to benefit the people using the code.

Yes, there are many reasons for following established principles, practices, and conventions. I recommend and follow many myself. But they're not the most important thing.

It doesn't matter how great the code is if you don't ship.

It's great that you've structured code to make it easy to maintain, but if you don't release bug fixes or new features, I question the value of the effort put into how the codebase is structured.

I've seen code that is technically "clean" but is slow and hard to understand and modify.

I recently met some developers at a company who highly prioritize "clean code." But, their shipping schedule was so slow that their customers complained about the infrequency of new features and updates. They had a massive backlog of "core" functionality that was expected to take years to be implemented. Their competitors had more features, more customers, and a better reputation. The developers at this company wanted to create a better product but admitted that their focus on "clean code" meant their development process wasn't as fast as it could be. I'm not implying it's the only issue or factor, but the product, their customers, and ultimately their business weren't as competitive as they could be because of an arbitrary set of rules they were enforcing upon themselves.

Obviously, there are multiple factors to consider when deciding what to prioritize. Priorities will also differ for products, domains, and personal preferences, but having a fixed rule that is never changed can hurt as much as it's designed to help.

Test coverage is also an important related factor. If I'm not writing something "test-first" (because sometimes this isn't practical or desirable), my guiding principle is that anything "non-trivial" should have tests. I define "non-trivial" as anything where I can't look at the code and immediately see and understand every code path and likely error case. It's not always perfect, but it's served me well for years.   

I don't have any "hard and fast rules" for when to play specific practices or when to structure code in specific ways, but "is this easy for me to read and understand?" is my guiding principle. And if I'm working with a team, having code reviews can verify that others working on the code can read and understand it too.

If I can understand it, I'm aware of the potential consequences of any changes, regardless of how it's structured.

I'm curious if others have general principles for planning and structuring code. Anything that doesn't include "must" or "always" (or treats "should" like "must") but instead acknowledges the complexities of managing multiple priorities in different circumstances.


Post a Comment

I get a lot of comment spam :( - moderation may take a while.