This article would be significantly better if it suggested any way to measure the "understandability" of code.

Even just proposing standard language for a survey question, like Net Promoter Score, would help.

As of today, it seems inappropriate to call understandability a "metric." What's a metric that can't be measured?

> if it suggested any way to measure the "understandability" of code.

There's no reason to measure it, just don't let people merge difficult-to-understand code into the codebase. The best comment you can leave on a PR is always, "I don't understand this, please rewrite it." People hate hearing it, they'd much prefer it if you'd show them some new trick or something, but that's not nearly as valuable to the company or whatever.

I’d be really annoyed if someone said “I don’t understand this” and immediately jumped to the conclusion of “rewrite it”.

It’s reasonable to assume there are times that complex problems require complex solutions. Saying “this code feels like it could be simpler, have you tried x?” would accomplish the same goal without the aggressive and lazy tone imo.

I get your point. Obviously you shouldn't gratuitously be a dick to people, and I was being a little bit flippant with my phrasing. On the other hand, being able to understand the code is an extremely low bar, and if you're writing code that other people can't understand then at best it shows a lack of basic respect for your coworkers, and at worst it's a form of employee theft from your employer.

If you sent in an article to a magazine as a freelancer and the editors didn't understand what you were trying to say, then you probably wouldn't even get a response. And if you did it repeatedly they'd probably block your email address.

Obviously no one is going to immediately intuitively understand a 1,000 character regex. But I'm sure we've all seen people who have treated basic CRUD apps like obfuscated C competitions.

> There's no reason to measure it, just don't let people merge difficult-to-understand code into the codebase.

The problem is that it ends up saying more about the maintainer than about understandability.

Is object oriented program hard to understand?

Is C with manual memory management hard to understand?

Are genetics hard to understand?

Is functional style programming hard to understand?

Is SIMD hard to understand?

Is code that uses linear algebra hard to understand?

Different people, and even the same person over time, will have different answers to these questions.

All true. But given a team with some mix of backgrounds and talents, some code is going to be easier to understand than other code. Write the code the way that is easier for the team to understand. Write it for the team you have, not for posterity or to impress random people on message boards on the internet.

Code complexity is a thing. It doesnt describe understandability but its a pretty decent proxy in my experience.

> In 1976, Thomas McCabe Snr proposed a metric for calculating code complexity, called Cyclomatic Complexity.

https://blog.codacy.com/an-in-depth-explanation-of-code-comp...

There is also likely some simple metrics you could get by looking at names of things alone.

Common substrings, length, and diversity of names are probably decent indicators.

Understandability here is more of an umbrella term for the system as a whole, cyclomatic complexity is generally only useful for much more isolated chunks of code. Reducing CC can also make the the system as a whole less understandable, moving an inner loop into it's own function for a simple example will reduce the cyclomatic complexity of the outer function yet the complexity hasn't really changed and now there is more indirection for the developer to deal with. It's a good tool for telling you how complicated a piece of code is, but generally there aren't many options to reduce it other than hacking the metric and making the system as a whole more complicated and less understandable.

I wonder if there is any comprehension metrics we could use in its place, similar how you can measure reading comprehension levels of certain text?

The article doesn't really get into specifics.

I think a good way to improve the understandability of code is via something I am calling "Locality of Behaviour":

https://htmx.org/locality-of-behaviour/

Exactly what I was thinking as I was browsing this thread. If I can understand the code by visiting as few files as possible and reading as few lines as possible and not having worry about finding those, job done.

There should be a metric that indicates aggregate LoB for a codebase. Simplistically, cluster references of all entities (variables, functions etc depending on the language), calculate the overlap of those clusters and aggregate them. Track this metric over time and when it breaches a certain threshold, refactor until it’s back to where you want it to be.

People always choose to measure the easy thing to measure instead of trying to measure the important, but often difficult, thing to measure.

For example I often see people obsessed about tracking time spent on something instead of measuring the actual outputs and results.

Yes it is difficult to even define "results" and then metrics which actually matter. Most managers confuse the actual functionality of code and easy metrics like lines od code, number of widgets implemented or jira tickets closed, none of which reflect value added to the org. But choosing to measure process inputs such as time spent on something or how much hard work somebody put at it is equally as bad if not worse.

Is it just me or this article just a sequence of truisms and platitudes a la "the only thing constant is change" and "complex systems are hard to understand"?

I mean, advice such as "start with a high-quality workforce" applies to every industry and isn't helpful at all in the given context...

I couldn't find a single hint at what actually constitutes "understandability" as a measurable metric that one can track and assign a score to based on well-defined criteria.

While certainly well intended, there's very little substance in the article.

I think it's worth noting that this a relative, as well as contextual.

For example, I recently heard a CTO at an agency tell a story about a new client. The previous agency had engineered something relative esoteric. Something that while understandable was also somewhat fragile, and took time to bring back from going down. In ecommerce, time is money. The client's biz needs went beyond the system being understandable.

Isn't that UX?

Not really. User Experience typically applies to the frontend. What the user sees and experiences.

That said, you could,in an abstract way, say Understandablity is the UX for the development team. Works for me ;)

> What the user sees and experiences

Eh, depends how you define "experiences" and "sees".

A lot of people think UX is about aesthetics and animations which is mostly false.

UX is more about usability and testing a product with real users.

UX is User Experience (external to the product).

This would be DX, Dev Experience (internal to the product).

Not saying you're wrong, but DX to me is more related to writing code, using commands, etc, not so much the understanding of how the project works.

Also, developers using something are also users, no?

It gets blurry. The bigger question is: can you reason about changes to the system. You need enough overall project and code-local context to do that. Nothing fixes spaghetti code, but tooling can improve you ability to model what is going on. IDEs can give live context inferred via static analysis, or pull together definitions from different files. REPL for introspection can be a big boon. Frameworks forcing conventions help with the principle of least surprise. Good CI/CD practices, create strong feedback loops that improve code quality rather than letting deadlines allow for not fully-understood code to slip through due to aggregate complexity, etc ...