
What does code readability mean? - gregjor
http://typicalprogrammer.com/what-does-code-readability-mean
======
virgilp
> “Good code is simple” doesn’t actually say anything. [...] What we call
> “simple” depends on our experience, skills, interest, patience, and
> curiosity.

I like Rich Hickey's stance on this: "simple" is objective (antonym:
"complex"), whereas "easy" is subjective (antonym: "hard"). Easy depends on
skills, interest, patience, curiosity - but simple does not. Simple is about
lack of intertwining of concerns. About writing code that can be understood
without "bringing in" the entire codebase into your mind. Like, you can
understand a pure function just by looking at it (it's simple). If it modifies
or uses a global variable, now you have to look at all the places that "touch"
that global variable, in order to understand what your function does; the code
is thus much more complex.

With that definition - it's absolutely correct to say that the code should be
as simple as possible. And that writing simple code is typically very hard.

~~~
olau
> With that definition - it's absolutely correct to say that the code should
> be as simple as possible.

Yet, it is humans who need to read it. This is the end goal.

If you rewrite the code to satisfy a theoretical objective criteria of
simplicity, but end up with something that people reading the code find harder
to read, then you have failed.

It's the same when you design a UI.

~~~
virgilp
But if you don't have an objective criteria of simplicity, how can you even
hope to have universal agreement of what is "simpler"?

Humans are complicated beasts. Saying "people find the code harder to read"
doesn't help me know what I should do. If I have no objective criteria, then
it must be subjective, and then all that "simple" means is that "this is
easiest for me _right now_ " \- which, from experience, I claim to be a very
unlikely path to produce code that multiple people agree to be "simple".
(except if the problem was trivial to begin with - but then, who cares?)

~~~
vec
"Which is the better painting, Van Gogh's _Starry Night_ or Seurat's _La
Grande Jatee_?" is a deeply subjective question.

"Which is the better painting, Van Gogh's _Starry Night_ or a kindergartener's
watercolor of their family?", on the other hand, appears to have a correct
answer.

There are multiple competing definitions of "simple" with respect to code and
multiple kinds of simplicity that often have to be traded off against one
another, and reasonable programmers can and do disagree about which
compromises to make and where. Code quality (including, but not limited to
legibility) is in many regards a subjective endeavor.

That doesn't mean, though, that all decisions are equally justifiable. Trust
your sense of aesthetics. It's usually trying to tell you something important,
even if you don't know how to put it into words yet. With subjective endeavors
there is no perfect, but there is usually better. Chase that.

~~~
virgilp
In your first example, both are exceptional, so really "which is better" is
irrelevant.

In the second, the difference is so big that it's obvious for anyone which is
better, but that still doesn't make it useful for getting better at painting.
"Paint more like a Van Gogh and less like a kindergarten kid" is not useful
advice.

People do have art critics and manuals that attempt to write down exactly what
made Van Gogh paintings great. Those writings are useful, and many artists do
indeed study them.

~~~
vec
Maybe I read too much into your original comment, but it reminded me of a
pitfall that I see too many engineering types fall into, namely that because
something can't be formalized then it must be arbitrary, unimportant, or both.
In particular, this seems like a counterproductive way to frame the issue:

> If I have no objective criteria, then it must be subjective, and then all
> that "simple" means is that "this is easiest for me right now"

Here's a few other (actionble) things that "simple" can mean.

    
    
        * seems to reliably be easiest for me every time I look at it
        * was judged to be better by the three or four people I could get to give me an opinion
        * follows a heuristic that a bunch of smart people all seem to agree generally makes things better
        * mirrors whatever we did on this project the last time we were in this situation
    

Even if all it means is "easiest for me right now", that's still probably
going to get better results than "the first thing that popped into my head
that might work".

There is no objective definition of simple. On behalf of the maintenance
programmers of the world, please don't take that to mean it's not worth trying
anyway.

~~~
virgilp
> There is no objective definition of simple.

Oh, I agree with that. What I meant was that "this doesn't mean there can't be
objective criteria about what is simple and what is not; or that it's futile
to attempt objective definitions of 'this is simple/this is not' ".

"Easiest for me right now", in my experience, only leads to simplicity in
trivial cases. Simplicity requires intense thought & explorations, it's never
easy (except, again, in trivial circumstances).

------
gabemart
The author consistently compares code language style to literature language
style, but I don't think it's a helpful comparison at all.

Literature operates by an intractably complex interaction between the words
written on the page and the mind of the reader. Exchanging a single word for
another may totally alter the effect of a passage, based on factors like the
meaning of the word, the associations the word has for each reader, and the
aesthetic appearance and sound of the word.

Moreover, we have no objective way of measuring the effect of literature. We
don't have a test that can measure how much more empathetic I become after
reading a novel, or how much more I understand the human experience.

Computer code typically has measurable outcomes. While "readability" may still
be a relatively subjective measure, we can at least say "these two versions of
this function are equivalent" if the _outcome_ is the same - the array is
sorted correctly, the transaction amount is calculated correctly, the graph is
rendered with the same pixels.

This means that editing computer code is nothing at all like editing
literature. The cliff-notes version of Macbeth can never produce the same
effect in the mind of the reader as reading Macbeth -- but a function that is
_subjectively_ easier to read can be shown _objectively_ to produce the same
effect as the original function.

~~~
gregjor
Good point, I agree with everything you wrote. I didn't intend to compare code
language _style_ to literature, maybe I failed to make that clear.

I tried to make the more subtle comparison that some programmers react
reflexively to code that doesn't look familiar to them and call it unreadable,
the same way that a person unfamiliar with Shakespeare and unprepared (or
unwilling) to make the effort to read it will dismiss _Macbeth_ as hard to
read.

A person new to Shakespeare picking up _Macbeth_ will find the book
challenging because of the antique language, the poetic form and dramatic
devices, maybe the historical setting and allusions. A person new to a body of
programming code may react the same way, for similar reasons. A reader new to
Shakespeare probably knows that the problem lies in their own abilities and
patience, not in the book. A programmer new to a body of code will tend to
blame the code, in my experience.

~~~
JamesBarney
Good writing is not necessarily readable writing. Shakespearean works are good
writing, but they are most certainly not easily readable. There is code that
is great code because for many other reasons than readability.(Like
performance, correctness, robustness)

Easy to read writing is simple and concrete. Code that is easy to understand
is also simple and concrete.

Complexity and abstraction push away understanding like two positive magnets.
But sometimes readability is worth sacrificing to achieve a separate goal with
the code.

~~~
Alex3917
> they are most certainly not easily readable

They would have been easy to understand by folks who were alive at the time
they were written when performed on stage. The only unfamiliar words would
have been the ones he coined, but most of those were easy cognates from latin.
If Shakespeare wrote the same works today then he'd be a terrible writer.

------
tboyd47
This is a thought-provoking and well-written blog post about programmer biases
when it comes to reading, and judging, other people's code.

The author is making the point that code readability is ultimately in the eye
of the beholder. I've come to share the author's views, and I have to say I
don't hear it said much in programming culture. At most places I've worked,
there's this culture of constant refactoring under the guise of "continuous
improvement," when really, if you look closely, it's really motivated out of
disdain for the last developer's programming style, and in my opinion, a
general aversion to reading code.

Reading code is about 10x as hard as writing it. It takes more concentration,
it's less fun, it's harder, and it doesn't impress anyone. You have to know
the language better than the person who wrote it, because not only do you have
to understand why the code does what they intended it to, but you also have to
understand why the code does other things they _didn 't_ intend (a.k.a. bugs).
But in my experience, you save your team a lot more time and energy in the
long run by preferring to read and understand existing code.

~~~
ebiester
Alternatively, we refactor because the right abstraction for the previous
phase of the project is not the right abstraction for the current or next
phase of the project.

While I do have a respect for Chesterson's Fence as a concept, sometimes the
answer to "why is it this way" is "we were learning as we went, and if we did
it again, we'd do it another way."

I look at it this way: When you look at an older city built before the age of
the car, they were built to be tiny to start, not more than a set of shacks.
As the town built wealth, the buildings went to more sturdy, to multi-story,
and to more ornate structures. Similarly, our code should start simple and
dirty, then cleaned up as it has proved its worth, and then refactored to more
robust patterns as the code has built the wealth (and demand) to justify it.

We should consider rewrites, then, as a sign of value, rather than as a sign
of the previous programmer's failure.

~~~
dahart
> sometimes the answer to "why is it this way" is "we were learning as we
> went, and if we did it again, we'd do it another way."

This is true! In fact there's a lot of that, in my own experience. Rewrites
are probably most useful on code you wrote, rather than on someone else's, and
right when you realize what went wrong, while you're still intimately familiar
with the old code.

I've watched two different companies follow the "things will be so much better
if we rewrite" logic and rationalize large scale rewrites that cost millions,
and years, and failed to achieve the aims of doing it better the second time.

Rewrites should be considered a sign of value only if we actually learned from
out mistakes, _only_ if both everything wrong with the old code _and_
everything right with the old code are well understood. If you rewrite
anything substantial before that, you're just guessing, and you're most likely
(in my experience) going to suffer taking longer than you want and making the
same mistakes again. I've seen that happen to many very smart people.

So there's a balance. Rewrites are sometimes valuable, but not automatically
valuable. Sometimes rewrites are very harmful. The best chance you have of
knowing which one is to read lots and lots of code before you start, to make
absolutely sure that the code you're replacing is never being replaced only
because the readers didn't understand it or didn't like it's patterns.

OTOH, if you have complete test coverage in place before a rewrite, you can
freely annihilate and redo large portions of code without having to study too
hard.

~~~
tboyd47
I've seen smart people fall into the following trap:

1\. Previous developers did X and X is bad, therefore, their code needs to be
rewritten without doing X.

2\. Oh crap - turns out, the new code has all these requirements to match the
old code's functionality in ways we didn't expect (letters A-W).

3\. Okay, so we're doing Y and Z in the rewrite, knowing it's pretty bad,
because we didn't know we'd have to do A-W and now we're short on time. Oh,
and parts of the code still do X.

Now, wait a year for one third of the team to leave because they're rushed,
overworked, burnt out, going in a different direction... and another third to
get laid off because the project went way over time and budget...

4\. Previous developers did X, Y, and Z, and X, Y, and Z are bad, therefore,
their code must be rewritten...

------
DavidWoof
This reminds me of the discussion of "quality" in _Zen and the Art of
Motorcycle Maintenance_ , where the class finds that while nobody can exactly
define quality, when confronted with high and low quality writing everybody
could recognize which was which.

As OP realizes, nobody thinks Knuth's ACP is poorly written even though it's
hard. The elegance is obvious, even if the algorithm is hard to understand. On
the opposite end, I've come across FizzBuzz implementations from job
candidates that I've struggled to follow. I've often seen a 10-1 difference in
code sizes for different implementations of the same problem, and while
there's edge cases where smaller code can start to become confusing, generally
every dev on the team recognizes which of the two is more readable.

I have no problem with the idea that there can be subjectivity in discussions
of readability. But the idea that readability is _purely_ subjective, or only
has to do with differing styles is ridiculous. In fact, I don't believe for a
second that OP really believes this. He wants to make a point about
subjectivity, which is fine, but for some reason has chosen to write it in
this exaggerated clickbait style.

~~~
gregjor
I had _Zen and the Art of Motorcycle Maintenance_ in mind when thinking about
readability, because that describes one kind of quality we care about.

I don't think I wrote that "readability is purely subjective," I certainly
didn't mean to imply that. I did mean to make a point about subjectivity.

Sorry you didn't like the style. I write articles because I enjoy writing and
I think I have ideas worth sharing. I don't have ads or affiliate links on my
site, so I have no incentive to post clickbait.

------
tekstar
I once had a developer who consistently wrote unreadable code while trying to
be clever. To give him useful feedback I needed to come up with a black and
white heuristic for knowing if code is readable or not.

The heuristic is this: Readable code can be explained in English sentences in
one pass.

Your code tells a story. When you read it do you introduce the characters in
the right order? Halfway through a complex passage do you reference something
out of context without explaining it? Give concepts valid names to help the
reader build context on your intent.

The best part of this heuristic is that you can get the code author to attempt
to read back their own code, and trip over their own convolutions, and realize
where there is opportunity to simplify.

We all worked on the same codebase so a reasonable shared understanding of the
concepts was assumed.

This blog post throws various situations into the mix to try to be contentious
or something but misses the point.

~~~
gregjor
That's called the telephone test. From _The Elements of Programming Style_
(referenced in my article):

"Use the telephone test for readability. If someone could understand your code
when read aloud over the telephone, it's clear enough. If not, then it needs
rewriting."

I agree that the telephone test heuristic gives you an idea of readability,
but in 1974 Kernighan and Plauger assumed someone one the other end of the
phone who knew Fortran or PL/I.

Trying to explain a moderately complex class hierarchy or a factory function
or a closure over the phone would prove challenging. I could explain the
_purpose_ of the code at a level someone else could understand, but they might
not recognize the implementation when looking at the code.

A few years ago, doing maintenance on an abandoned production system, I came
across a function with the comment "Produce a unique six-digit identifier that
doesn't start with 0". The original programmer could have explained that to me
over the phone, but his implementation (in PHP) was not clear at first or
second glance. I expected this:

    
    
      $id = rand(100000, 999999);
    

Instead the function started with a loop to get the first digit:

    
    
      while (true) {
          $first = rand(0, 9);
          if ($first != 0) break;
      }
    

I'm not making this up.

Then another loop to pick five more digits in the range 0..9. Then a database
query to see if that ID was used, and if it was the function called itself
recursively. I'm not kidding.

So while I would have understood the problem _described_ over the phone, I
didn't recognize the implementation at first sight. If the programmer had read
the code to me over the phone I might have assumed I was missing some
requirement that led to this overly-complicated implementation. Not all of the
code looked like this so I don't know how the original programmer got wound
around the axle on this function.

------
pjc50
> By analogy, plenty of people find reading Homer, Shakespeare, or Nabokov
> difficult and challenging, but we don’t say “Macbeth is unreadable.”

What of Joyce's _Ulysses_?

The thing is, most authors _do_ put considerable effort into readability,
because it helps you get read, published and paid. There's an interesting
parallel with this article - writer:programmer :: critique group:code review.

> Programmers, prone to investing their ego in their code, worry about
> criticism from a lot of people they don’t know. Slurs about competency
> abound in programmer forums. Code samples out of context get critiqued and
> subjected to stylistic nit-picking. That process can prove helpful for
> programmers with thick skins who can interpret criticism as either useful
> mentoring or useless insults. Less experienced programmers can get misled
> and brow-beaten. Public code reviews create a kind of programmer performance
> art, when programmers write code to impress other programmers, or to avoid
> withering criticism from self-appointed experts

s/programmer/author and it still holds. As does much of the rest of the
article.

I would say that programmer education really does underplay reading code.
Students are taught to write small pieces and may never be shown a large
novel-sized lump of code unless they go looking for it.

~~~
olavk
Ulysses is not unreadable, it just takes a lot of effort. For programming, the
criteria is not if it is hard to read, but whether the same thing could be
expressed in way that would be simpler and easier to read. But I not sure to
what extent this could be applied to poetry, since the expression in language
is in itself "the thing".

~~~
pjc50
"Unreadable" in this whole discussion should be taken as meaning "requires
effort that the reader is not willing to expend", not an absolute. There are
very few things that are impossible to read at all, even the notoriously and
deliberately unintelligible stunt languages like INTERCAL and brainf __k.

~~~
pluma
I'd even go so far to say that the only way something can be _literally_
unreadable is if it is physically impossible to do so (e.g. unrecoverable
data) or there is not yet any known way of determining the meaning of a given
text (e.g. the Voynich manuscript).

But of course that isn't what is meant when we say something is unreadable
because humans don't deal in absolutes (though programmers sometimes do, which
is why programmers are so fond of using overly noncommital language like
"should" and "most likely").

------
iovrthoughtthis
This is a fantastic post that asks a question that I think many people just
jump over on their way to "being right".

What exactly does the thing we are talking about mean?

In this case "code readability".

I would add to this that "code readability" only means something to me in the
context of it's intended audience. Code is readable when it is simple to
decipher by the people that the author intended to decipher it. For anyone
else to hold it to standards outside of those agreed upon by the author and
the intended audience seems silly.

~~~
pkolaczk
A problem arises, if there exists no group of people that the author had in
mind when writing the code. Some programmers really just code "so that it
works" and don't care about readability at all. That's why we have code
reviews - a code review is an attempt to read the code. If at least one
reviewer understood the code, then we can assume it was not completely
unreadable.

------
lambic
I often refactor code as a way to understand it; working through the logic and
rewriting it in my own style helps me get a good grasp of what the original
code was doing.

Sometimes I throw away that refactoring if I realise that the code I was
having trouble understanding was actually fairly well written and I just need
to sprinkle in some comments.

------
arkh
Doing a lot of code maintenance what is the worst is most "smart" things.
Every time I get to some indirection to be smart and I can't just ctrl-click
on some line to get to the definition I'm angry.

I don't want to check what is there at runtime once the configuration has been
loaded. I don't like going through 10 get("serviceName")->handleSomething()
and having to check where those services are defined. I really don't like
having to go through 20 abstractions trying to find who fucked some data on
the way in my debugger.

I know, your 3 loc per method codebase felt good to write. The added useless
junk around the code (function definition and {} on their line) means even
with a 4k monitor I can't see your full algo in one page.

Using reflection magic? Please don't. I like dumb code which shows what it
does and can easily be followed.

And that's coming from someone who likes the ${whatever returns a string}
method of defining dynamically named variables in php: it feels always fun to
write. But it is a hindrance when debugging. And when debugging the less
"small shit" you have to deal with, the more brainpower you have to focus on
finding the problem.

------
tomxor
I think it's necessary to expand on the authors definition of "complex" vs
"simple"... Things can be "complex" and thus hard to read for many difference
reasons:

At one extreme the reader is definitely responsible for things like
understanding an underlying algorithm - the algorithm chosen might be a good
choice, but it might also be very complex. It's not always possible to clearly
convey an efficient implementation of a complex algorithm in code - It could
be argued at the most that the author should name the algo in a comment, but
litering the implementation with comments describing the algorithm would make
it harder to read for someone who is familiar with the algorithm.

At the other extreme there are all kinds of unnecessary complexity that make
it hard to read, some by poorly suited forced design patterns, some by cruft
that accumulates and some by un-refactored growth (big ball of mud).

One of my pet hates is highly layered object oriented code where someone has
gone to painful ends to generalise and modularise the fuck out of every single
routine to the point that the overhead of traversing the hierarchy to
determine what actually happens in what order with what side effects when you
call one of the outer layers of that ginormous onion is humanly impractical.
I'd call that unreadable code due to complexity that the authors are
responsible for.

------
tjwii
Readablility is definitely not similar to understanding. The problem I have
with reading code from other codebases is not understanding the coherence.
Naming of variables is a great deal here, one poorly chosen name can totally
confuse me. And still it is highly subjective because an other developer might
instantly see the relation just by chance.

If you're unfortunate enough to code full-stack web apps then you'll likely be
dealing with hundreds of npm libraries you've never heard of! How can you know
all possible effects and side effects of 1 simple call to a method in some
library? That alone would be a quite a study in some/most cases.

It would be great if for any project you can find at least an overview and
explanation of the coherence that the files and used modules have in relation
to each other. But unfortunately that is often missing already to start with,
so you end up with a vast and often unsolvable puzzle.

Programming computers is still in its infancy. We definitely need better tools
and structures to understand what's going on IMHO. It makes me laugh when
people tell me they solve this with a linter.

------
Quarrelsome
I work on a system where arbitrary property access results in database round-
trips. So the following code:

foreach(var b in a.Bs) { if(b.Data != null) { ThisIsInteresting(b); } }

results in a.Bs.Count + 1 round-trips to the server and then database if these
fields have not been accessed before. (a.Bs is one and b.Data != null is one
as well).

This is a fine example of what I'd call "unreadable" code because there is so
much activity that is implied by actions that in other systems are completely
innocent and well isolated.

Also there is the point of cognitive load. If your entire application was
simply one function it is technically "readable" but the cognitive load of
trying to work out what is in scope and what might change a given variable is
too high to read without extraordinary effort. When working in such systems
(as I have before) you HAVE to rewrite it to even start reading it because a
human memory cannot hold all that information at one time.

I think brushing it all of this off as "the reader isn't reading well enough"
is disingenuous.

------
yulapshun
To read code is to understand it. It has little to do with style but more to
do with program structure and abstraction layers. I've maintained a PHP
codebase with some of the worst code I've ever seen. For Example:

1\. A function with a few thousand lines of code, accepting dozens of
parameter. The body is made up of some nested switch-case and if-else.

2\. Instead of using constructors, every class has a static method that does
nothing but initialize itself.

3\. A class which queries DB and generate HTML, with nearly a hundred public
variable. A few levels of sub classes with functions to update those
variables.

When a piece of code is not obvious in what it's doing, I'll call it
unreadable. In some cases this is acceptable, for example in some clever
algorithm
([https://en.wikipedia.org/wiki/Fast_inverse_square_root](https://en.wikipedia.org/wiki/Fast_inverse_square_root)),
but it is still what it is, unreadable.

------
pkolaczk
There is often a world of a difference between code hard to read because it
tries to solve a complex problem or is written in a paradigm I haven't learned
yet, and code hard to read, because its author was just plain sloppy, and
didn't properly care about naming or decomposition. Distinguishing between
these two cases is a matter of enough experience.

------
aplorbust
"Greg Jorgenson is a typical programmer."

Then who are all these commenters in mailing lists, forums, blog posts and
source control systems who are proclaiming code they cannot read as
"unreadable" or 'unmaintainable"?

Clearly the author is aware these comments fall into the categories he
mentions; they are reframing "I can't read this code" into some sort of
pseudo-objectivity.

If typical programmers are aware of this practice, then who are these
commenters labelling things they cannot read as "unreadable" or
"unmaintainable"?

Are they "typical programmers"?

Can we respond to those labelling code as "unreadable" or "unmaintable" by
pointing out that they really mean "I cannot read this code"?

Will they acknowledge, "Yes, what I meant was I do not know the language well-
enough to understand that code, but others might be able to read and edit it."

------
bluesnowmonkey
The article hints at it, but your sense of the readability of a codebase
changes the longer you are exposed to it. Patterns that make it easier to
become moderately competent in a particular codebase can actually make it
harder to become expert. So if you want to maximize readability, you need to
estimate how long future maintainers will live with your code.

Will they drop in and do a single commit and never look at it again? Then make
sure everything you need to understand a piece of code is right there next to
it.

Will they work on it for a long time, changing many parts? Then be very
consistent with the patterns and idioms you use across the project, so that
their previous experience changing other parts of it helps them understand how
to make the next change.

------
jasonmaydie
I don't like the shakespeare analogy because not every written piece of code
is supposed to be a work of art. You wouldn't write an instruction manual like
you would write Macbeth. Most of the time there's really no value in writing
cryptic code

~~~
Miss_Vee22
You are saying that programming is the same as an instruction manual?
Programming is art. Nearly every objective in programming will have over a
million potential implementations. Personality, wisdom, and mood are in every
program (obviously there are some Hello World exceptions) just like artistic
writing and nothing like an instruction manual. Machine code is an instruction
manual compiled by a computer, a program is a piece of art created by humans.

~~~
jasonmaydie
well no. You can write artistic code, people do that in coding all the time
(in programming contests, sample code, your own code etc) but the real goal of
writing code is to perform a certain task. The execution of those instructions
is what matters, not the style of how the code written.

So yea not all code is art.

------
catpolice
There's a sense of "unreadable" that I sometimes use that means "the code does
not contain the information that you need to understand how it will typically
function". E.g. things that have internal control flow determined by complex
input processing where the input is ill-specified. It can be essentially
impossible to put together a mental picture of the operation of the program,
because key parts are essentially unspecified.

And there's a related sense that I occasionally use to describe code that's so
difficult to follow (in the sense that the control flow or structure is
needless obfuscated) that the process of trying to understand it doesn't
really resemble simply "reading".

Some examples:

A function is called in many places in es6 code. I want to see its definition,
my editor can't figure it out. I look at the import statement, it's imported
from a file. I open that file, and all it does is export * from a dozen other
files - so now all I know is that it's in one of these dozen files. I am
reduced to doing something like grepping for the function name and looking for
the case that looks more like a definition than a call. At one point I was
reading the code, now I'm doing something related and more involved than just
reading.

Or, in this system components emit message objects with a "title" field. The
messages are dispatched to dozens of functions across files that inspect the
title field to determine if they do anything with it. Only they don't just do
a simple comparison against a string literal, they check if the title meets a
regex. There are many of these different regexes. I read the code that emits
the message and I want to know what behaviors the message being sent out
triggers - how do I track that down? I can't even grep for the message title.
In order to make a list of things this message might do, I have to look
through everything that might possibly handle the message and try to figure
out which regexes are triggered.

In this case, reading is involved in the same way that reading through a math
book and solving the exercises does involve reading - that's not where most of
the work comes from.

------
bradfa
The biggest helper for me when trying to read other peoples' code is having a
document (or documents) which describe what the heck the code is supposed to
be doing in human terms. This is especially true when I'm not super familiar
with the business history, long forgotten bug fixes, and nuance which was
previously worked around or implemented.

Software documentation almost always sucks, in my experience. When I do find
well written documentation that reflects the code, it becomes much easier to
understand the code quickly so that I can make the changes I want to make.

But nobody likes writing documentation.

------
harrisjt
Clean Code I think is the best resource on readability. Your code self-
documenting while following simple software principles is difficult but ideal.

------
deckar01
Time is a commodity. The extra time spent reviewing or maintaining code that
is difficult to read would be better spent writing the code well the first
time.

In open source development, a maintainer’s time is often extremely limited. If
you can’t make your code easily readable for that maintainer, then your
contribution is worthless. You have created an asset with a transaction fee
that prices you out of the market.

------
stinos
The author is spot on for 'standard' code styles. However when you enter the
realm of crazy code styles (say, all code of the program in one single line,
obfuscated code not meant for humans to read and so on), wouldn't we all agree
that is in fact, objectively, unreadable? Beacuse actually reading it is
simply too hard no matter how skilled and knowledgable you are? (note none of
the OP's points cover this, except for 'The code offends my sense of
aesthetics' maybe, but by a stretch).

And extending this somewhat further, I have already seen code written by
humans which I am confident the vast majority of programmers would consider
unreadable. Unfortunately including the guy who wrote it.. We're talking
mixing indent witdhs/seemingly mixing all known code styles/complete lack of
consistency/lines of hundreds of characters/big chunks of >20 newlines/... I
think there is a point where this becomes unredable and it's not the reader
who is to be 'blamed'.

~~~
dang
> _wouldn 't we all agree that is in fact, objectively, unreadable_

No, because there's a rich body of counterexamples in the array-oriented
languages (APL, K, J). Everyone who doesn't know these languages immediately
dismisses programs written in them as unreadable, but that is far from the
truth.

If you spend some time in the alternate programming universe that such
languages inhabit, you'll get into your bones the knowledge that readability
is relative both to language and to reader, and you'll start to think about
simplicity in a deeper way. (By "you" I don't mean you personally, of course,
I mean everyhacker.)

------
danschumann
Some good points. I think code-readability should be measured by people who
are as accustomed as possible to the code base. IE, if you wrote all the code,
how quickly can you refresh your memory ( 6 months later ), as well as trace
down bugs.

------
dablya
There is a difference between reading legacy code without empathy (sympathy?
pretty sure it's empathy) and calling code equivalent of Macbeth as unreadable
when Cliff's Notes would do...

------
simonblack
Code readability is when you are able to pick up the source of a program that
you haven't looked at in 10 years and instantly understand it without having
to study it intently.

------
palakchokshi
public class A

{

    
    
       private int exid;
    
       private string M;
    
       public A()
    
       {
    
          M = "The result is:";
    
       }
    
       public string y(int u, int v)
    
       {
    
          return M + (u+v).ToString();
    
       }
    

}

public static void Main()

{

    
    
       Console.WriteLine(new A().y(1,3));
    

}

Now add hundreds of lines of such code and you'll get unreadable code. It is
not in the eyes of the reader, some code is just unreadable.

This is an extreme example though.

------
sigjuice
For me code readability means that the code I write today makes sense to me
next week :p

~~~
sound1
Totally agree with thus one :-)

------
LanceH
You'll know it when you see it.

------
crdoconnor
Over time the first thing I've come to desire more than 'intrinsic'
readability when joining a new project is a decent, up to date, hyperlinked
glossary with all of the relevant acronyms and terms that will be used in the
code. I've had variations on this conversation many times before:

* New coworker (me): What's an XYZ? (some core thing in the system)

* Coworker 1: An XYZ is [blah blah blah].

* Coworker 2: Actually, an XYZ may not be [blah blah] it could be [blah].

* Coworker 1: No! That's not right!

* Me: ugh...

