
Understandability in software - signa11
https://www.infoq.com/articles/understandability-metric-not-tracking/
======
dfabulich
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?

~~~
Alex3917
> 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.

~~~
frankandstein
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.

~~~
Alex3917
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.

------
recursivedoubts
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/](https://htmx.org/locality-of-
behaviour/)

~~~
dpenguin
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.

------
snidane
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.

------
qayxc
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.

------
chiefalchemist
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.

------
pier25
Isn't that UX?

~~~
chiefalchemist
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 ;)

~~~
pier25
> 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.

