Readability of a Computer Program

I like duck typing

Readability means how easy the computer program is to understand. Computer program readability is slightly equivalent to readability in literacy. Any program that ends up to production should ultimately be readable. Readable programs are more valuable than their unreadable counterparts because:

They require less maintenance. The author itself has understood better a problem he's working on.
They are easier to maintain and work with, as it is easier to study them.
They are easier to document, as it is easier to study them.
Over time, they more likely become stable, as more people may get to study them.

There is not a magic sauce that makes readable programs. To improve, study, read programs written by other people and write some programs yourself. This blog post contains some things you could pay attention to get you started.

Remove unnecessary

perfection is finally attained not when there is no longer anything to add, but when there is no longer anything to take away

It has been asserted that was written by famous poet and writer, Antoine de Saint Exupéry. Is that abstraction or construct required for the program to work? Is that comment required for good understanding? Not required? Remove it. Shorter programs are easier to read.

The noise is the worst thing for readability your program may contain: If your programming language has notation or conventions that are verbose or illegible. Write your code in an other language instead.

One of the most common growth in computer programs is the repetition. If you find yourself copying something around, turn it into a function instead. If there are lot of occassional special cases for your program, learn about data driven programming. Rather than doing:

a(x,y) b(x,y) c(x,y) d(x,y) ... thousand times

do:

for f in [a, b, c, d, ... thousand times]
    f(x,y)

Grepping -> Scanning -> Reading

It takes time to read, so people aren't reading everything. Experienced programmers are using a tool called grep, which can search through a directory for them. Consider that people do not always start reading the code from the beginning.

In fact, many people just scan code instead of reading. They might be interested about a particular function in the program and just ignore everything that doesn't have the right looking keyword.

Important things first

I always attempt to put the important or hardest thing first in my programs, to improve readability. The unimportant, obvious or very easy to understand things go to bottom of a file, because there they're out of the way. Only constants and import declarations make up an exception on this rule.

Shorter is better

Short sentences and concrete terms make the programs easier to understand. If a statement is too long, break it into pieces by subdividing things into variables. Refrain from using too long variable names. Give the good names to variables that appear broadly in the program. More local the variable is, shorter it can be. In extreme, counters or short for-loops may have single-character variables without impact on readability.

Do not avoid advanced constructs provided by the language, if they make the programs easier to read. A qualified programmer is your audience, and they should understand their languages. If special vocabulary is required in the program, explain the vocabulary in the documentation.

Language matters

The choice of programming language has profound effect on readability.

More complex the syntax is, harder the language is to learn. But readability improves.
Some language constructs and conventions improve readability in limited manner. Iterators in python simplify about any program. Operator overloading can improve readability for vector or matrix algebra, if they're missing from the language.

Homoiconicity is really interesting aspect by program readability perspective. It allows the user to create her own language constructs. Lisp syntax lives on this property while being one of the simplest programming language notations this far. Unfortunately that notation itself is very unreadable.

Late optimization

Program optimization doesn't always destroy readability. The results are better if optimization is done late, when it is clear what the program needs to do. Sometimes it is possible to create a fast optimized and readable version of a program. But I'm unaware about whether this is always possible.

Overall

Readability of a programming language is itself really complex topic. There may be ways to measure readability, but one better remember a lesson from traditional literacy. Optimizing the text according to a particular metric may reduce readability instead of improving it.

Keep in mind readability isn't just for others. You're the first person reading the code you wrote. Readability builds up understanding of the program.