What does code readability mean?

submited by
Style Pass
2022-05-15 11:30:05

Programmers complain about readability and talk about bad code and unclean code, and the difficulties they run into trying to understand and maintain that code. What do we mean by readability? What makes code unreadable?

I hear programmers say that some code “is unreadable.” I read articles and books about readability and maintainability. What does that mean? Programmers usually attribute readability, or more often the lack of, to the code itself. But, like beauty, readability lies in the eyes of the beholder. When we say that some code “is unreadable” we actually mean one or more of:

Simply reframing the statement “this code is unreadable” as “I can’t read this code” puts the problem into perspective.

By analogy, plenty of people find reading Homer, Shakespeare, or Nabokov difficult and challenging, but we don’t say “Macbeth is unreadable.” We understand that the problem lies with the reader. We may not have sufficient experience with the language and idioms. We may not have enough historical and cultural context (similar to lacking domain expertise when looking at software). We may not have the patience or desire to invest time learning how to read a challenging book. Wikipedia articles and Cliff’s Notes exist to give tl;dr versions of books to people who can’t or don’t want to read the original. When we observe this tendency in other (non-programming) contexts we may interpret it as laziness or short attention span. When we react this way to code we blame the code and the original programmer.

When I first read Knuth’s The Art Of Computer Programming as a teenaged amateur programmer I found Knuth’s math-heavy analysis of algorithms hard to understand. I didn’t think Knuth doesn’t know how to write, or that his examples and explanations needed refactoring and dumbing-down. I thought I needed to learn more about the math and analytic techniques so I could competently understand the books. As my comfort with the math improved Knuth’s previously unreadable books yielded a lot of great information.

Leave a Comment