DEV Community

stereobooster
stereobooster

Posted on • Originally published at stereobooster.com on

Code readability metrics?

Let’s assume you need to build code-readability-meter. How would you do it?

What is code readability?

Readability is the ease with which a reader can understand a written text.

Wikipedia

Readability is what makes some texts easier to read than others.

The Principles of Readability

Many factors play into the readability of text. For example, contrast, font, choice of words and many more. (See: readability for natural languages)

Some factors are subjective e.g. depends on the reader - if the reader knows given programming language, if the reader knows the context if the reader familiar with the jargon, etc. There is a great talk on the subject: Laura Savino - Talk Session: Readable Code. She says that “readability needs a reader”.

Some factors are objective e.g. doesn’t depend on the reader - length of the text, indirection in code, etc.

Subjective factors

In my opinion the only way to control subjective factors of readability is with code reviews e.g. if every team memeber can read and understand give code.

Objective factors

On the other hand objective factors can be measured by the porgramm, for example, we can build graph of function calls or variables, types, clesses dependencies and measure depth of graph.

So the question is: which objective factors we can measure to detect code readability?

Goodhart’s law

When a measure becomes a target, it ceases to be a good measure

Wikipedia

I want to think about possible metrics of readability to better understand it, I don’t plan to make it one of those metrics like, test coverage or so called code quality.

Top comments (13)

Collapse
 
ahferroin7 profile image
Austin S. Hemmelgarn

Various measures of complexity come to mind, as they're often used as guideposts for when to sub-divide functions for readability.

Cyclomatic complexity is the most commonly used one, and is essentially a measure of possible paths through the control flow graph of the code, typically measured per function/subroutine. Higher cyclomatic complexity usually translates to the code being more difficult to understand, and always translates to it being harder to test.

The other big one is the Halstead complexity measures, which reason about various properties of the code based on the number of operators and operands (both total and distinct values). They're somewhat harder to calculate in a lot of languages than the cyclomatic complexity, though the 'difficulty' measure is arguably more useful for deciding on readability than the cyclomatic complexity is.

Collapse
 
stereobooster profile image
stereobooster • Edited

Not readability metrics

Length of text

I agree that 1000 LOC code is easier to read than 100,000 LOC code. But if the size of code samples comparable than length says nothing. I can easily imagine 500 LOC that is harder to read than 1000 LOC 🤷‍♀️.

Nobody reads code from cover to cover. Most of the time people read relevant pieces in small chunks, from that point of view length doesn't help to measure readability. Structure and "predictability" is more important.

Code formatting

I agree that homogeneously formatted code is easier to read. But on the other side, I don't think we need to measure instead we can use auto formatter, like Prettier, etc.

Collapse
 
josephtaylor profile image
J. Taylor O'Connor • Edited

Static analysis tools like Sonar can do some of this already, definitely the complexity measures Austin mentioned. Some other things that come to mind are:

  • class size in lines of code
  • levels of indentation (i like to keep it under 2)
  • number of parameters to a function
  • number of methods on an interface
  • number of break/continue statements inside loops
  • abbreviations in names (variables, functions, and types)

everyone working on the same pieces of code should definitely have a common formatting that’s performed on every file. Variations from the standard format could be measured.

Collapse
 
josephtaylor profile image
J. Taylor O'Connor • Edited

There’s the idea that you can follow a simple set of (arguably measurable by code) rules and you’ll end up with much more readable code. This topic always makes me think of this talk—following small rules can add up to big readability improvements.

Collapse
 
stereobooster profile image
stereobooster

I don't think that size (LOC or number of something) is readability metric. See my answer here dev.to/stereobooster/comment/m56f

Collapse
 
bradtaniguchi profile image
Brad

In my opinion the only way to control subjective factors of readability is with code reviews e.g. if every team member can read and understand give code.

I agree, your team could be filled with geniuses that write 1 liners that are "non-trivial and elegant". Or you team could be filled with random people with minimal code experience.

Slap on as many metrics as you want, it will just give you a number that ultimately means nothing.

I'd grab the "weakest programmer" and ask them to review some given code for readability. Worst case they learn something, best case the code should become more readable if it isn't simple.

The best kind of code should be easy to read even for a "beginner", but what a beginner depends on the company, culture and use case. :)

Collapse
 
stereobooster profile image
stereobooster

This approach kind of stops conversation. My idea is to understand what contributes to code readability, not to make it as ultimate measure (I mentioned Goodhart’s law).

Collapse
 
domas profile image
Domas Juodele

-self explanatory, which mean minimum comments.
-code can be read, not investigated.
-methods split by functional purpose, and should have single purpose the same applies for classes

code written for a human not for a machine :)

Collapse
 
stereobooster profile image
stereobooster

code can be read, not investigated.

Yes, but what does it mean? How to measure it?

methods split by functional purpose, and should have single purpose the same applies for classes

Sometimes those super tiny functions hard to read, you need constantly jump back and forward to read what the function does and you lose the context

Collapse
 
elmuerte profile image
Michiel Hendriks

I would not! Because there are no metrics that work.

I would define a code style, and that's the rule you live by. End of line!

I prefer tabs over spaces. If your project uses spaces, and I want to submit a patch, I uses spaces. If your project puts curly braces on new lines, and I want to submit a patch, I put curly braces on new lines.

Collapse
 
stereobooster profile image
stereobooster

I would not! Because there are no metrics that work.

yes yes, that is why I mentioned Goodhart’s law. This is exercise for imagination

Collapse
 
metcoder profile image
Carlos Fuentes

From my point of view, code readability is not something quantifiable but qualifiable. It's hard to measure the code readability based on how many lines, functions, indentations and so on. Code readability is more about grab characteristics, standards and any other tool to use it as a reference of how the code should be made in a way to make it easier to understand for everybody and not only the author.

Collapse
 
rimutaka profile image
Max

It would be cool if I could select a block of code in a repo or some code review app and press ? to indicate that I do not understand.