11
$\begingroup$

Readability is often intuitively synthesized. If you see some piece of code, you just know whether it is readable or not. But what are actual psychological, scientific explanations for this?

There are readability metrics for written text, but do they apply to source code as well? For example: I believe the word superiority effect to be applicable to source code. What other effects can be found while programming, that make code readable?

I am not looking for educated opinions or examples as in here or here, but for neural correlates or a perspective from cognitive sciences.

Improve this question
$\endgroup$
6
  • 1
    $\begingroup$ One thing that frequently inhibits readability is deviance from common patterns. When someone iterates over some collection, but starts with the second element, that's easily overlooked and can make the code "feel" more complex than it actually is. $\endgroup$
    – Joachim Sauer
    Apr 9, 2013 at 11:46
  • $\begingroup$ Deviance from common patterns also factors in when comparing "my" code to "their" code - you are used to your own patterns. $\endgroup$
    – MadKeithV
    Apr 9, 2013 at 11:52
  • 1
    $\begingroup$ There's no direct references in Code Complete under 34.3 Write Programs for People First, Computers Second. Have you had a look through the extensive biblography of that book for relevant sources? $\endgroup$
    – StuperUser
    Apr 9, 2013 at 12:11
  • $\begingroup$ There is research for metrics regarding software source code readability, based on readability metrics for natural languages: Buse and Weimer, Buse and Weimer, Dorn. These don't discuss the psychological roots, however, but may help address your second paragraph about applying readability metrics to source code, how to determine if code is readable, and how to make readable code. $\endgroup$
    – Thomas Owens
    Apr 9, 2013 at 13:50
  • 2
    $\begingroup$ A related link, on eye-tracking when reading code: blog.theincredibleholk.org/blog/2012/12/18/how-do-we-read-code $\endgroup$
    – Piotr Migdal
    Apr 11, 2013 at 10:36

3 Answers 3

Reset to default
12
$\begingroup$

Using the English language, given two sentences that say the same thing, what makes one more readable than the other? Usually terseness while retaining clarity and removing ambiguity.

The exact same things make code more readable. Remove everything that doesn't add anything, but don't remove things that do add information. And avoid ambiguity.

In code, we have the advantage that we can reuse similar pieces of text and replace specific values within them. If only we could do that with books, we could save a small rainforest.

On top of terseness, we have good use of punctuation and spacing. Ever tried to read a blog piece where there are no paragraphs whatsoever? That's what it's like reading code that isn't neatly spaced out.

The psychology of this is simple. Your brain receives all sorts of hints as to what it's reading. Try taking a long piece of text and printing it out (with a serif font) without paragraphs, then without periods and commas, or maybe switch punctuation marks (? => ., ! => :, etc), then in a sans-serif font.

You'll quickly see how much you rely on your brain's instincts when you're reading. Code is exactly the same. And herein lies a problem, because some things are certainly subjective. Or rather they are a matter of habit.

If you're used to seeing underscores preceding member variables, then you move to a company where they don't do that, your brain will still expect the same hints and it will be harder to read. But to change it would mess up everybody else in the team. It would be like moving to Spain and telling them to stop using the preceding inverse-question mark because it throws you off.

Design patterns are a similar thing. If everyone knows what a Builder Pattern does, then adding Builder to a class name gives everyone a lot of information. But if I have my own Bracksfort Pattern, that information only helps me, at least until other people start to ask me, or I document it and get the community to buy into it.

Improve this answer
$\endgroup$
6
  • 2
    $\begingroup$ This. I hate it when people say verbosity of code doesn't matter because IDE writes it or some other excuse. What about the reader who has to wade through all those lines while trying to find a signal from the noise? $\endgroup$
    – Esailija
    Apr 9, 2013 at 12:11
  • $\begingroup$ Great answer, outlining the underlying difficulty of defining what is "readability" $\endgroup$
    – Clement Herreman
    Apr 9, 2013 at 12:28
  • 1
    $\begingroup$ One main factor that makes code readable for me are variable names, e.g. $f versus $first_names. $\endgroup$
    – user1196
    Apr 12, 2013 at 7:23
  • $\begingroup$ @what: Well, yes. If I took a piece of English text and reduced all the nouns and adjectives to one letter, you might struggle to read that too. $\endgroup$
    – pdr
    Apr 12, 2013 at 19:31
  • $\begingroup$ Reducing code is a common practice, especially on heavy traffic sites. Look at the JavaScript code on a Google page: all variables are one or two letters, and there is almost no whitespace (no line breaks, no spaces, no tabs). That is unreadable code. So creating readable code might involve creating readable code and then reducing its volume by search and replace before you put it online. $\endgroup$
    – user1196
    Apr 13, 2013 at 9:55
7
$\begingroup$

This is my current area of research (I'm a Ph.D. student in computer science and cognitive science). Like you said, there are a large number of readability/complexity metrics, but very little research trying to quantify what makes a piece of code psychologically complex. For more information on qualitative studies and models, I'd highly recommend the 2001 book Software Design: Cognitive Aspects.

I've been running some experiments recently with the goal of developing a cognitive model that can "read" code like a human. The inspiration for my model largely comes from a 1995 paper by Simon Cant et. al.. In the paper, they lay down an (incomplete) foundation for a mathematical model that "chunks" small blocks of code into memory and "traces" to other parts of the program in order to resolve dependencies. I have a workshop paper titled "Cognitive architectures: a way forward for the psychology of programming" that suggests we may be able to built such a model on top of a cognitive architecture like ACT-R.

I'm currently writing up the results of one of my experiments. Once it's ready, I'll be posting about it on my blog (synesthesiam.com). In short, we had programmers of all different experience levels predict the output of 10 Python programs (each program had 2 or 3 versions). Some of them did the experiment in front of an eye-tracker, which will be another paper someday (hopefully) soon. The rest were from Mechanical Turk, and we observed interesting speed/accuracy differences that were not always in favor of the more experienced programmers.

Improve this answer
$\endgroup$
6
  • $\begingroup$ Welcome to the site. Thanks for sharing your expertise. $\endgroup$
    – Jeromy Anglim
    Apr 19, 2013 at 0:56
  • $\begingroup$ Hello user2925, thank you for your answer. I am too planning an experiment right now and I was wondering whether you could share some more of your experiences? $\endgroup$
    – cessor
    Apr 19, 2013 at 7:59
  • $\begingroup$ Hi @cessor. I'd be happy to share my experiences. What kind of experiment are you planning? $\endgroup$
    – Michael Hansen
    Apr 19, 2013 at 14:58
  • $\begingroup$ @MichaelHansen I think it would be best to discuss this in private! Could you send me an email to the address in my profile? :) $\endgroup$
    – cessor
    Apr 19, 2013 at 20:55
  • $\begingroup$ Update: I posted a paper about the experiment mentioned in my answer on arXiv. $\endgroup$
    – Michael Hansen
    Apr 22, 2013 at 13:52
2
$\begingroup$

What does "readability" mean in the context of cognitive sciences? Measurable effects of "readability" would include:

  • speed of cognitive processing (how long does it take a reader to understand what the code does)
  • completeness of understanding (how much of what the code does can a reader explain after reading it?)
  • effort of understanding (how depleted are the reader's cognitive resources, measurable by a follow up processing power test)

It would be easy to test differently "readable" variants of the same code. Sample research can be found through a Google Scholar query. I'm too lazy to read and summarize those papers for you ;-)

Improve this answer
$\endgroup$
1
  • $\begingroup$ Thank you for your answer! I believe that "Cognitive Processing" is too abstract. The speed of the lexical access for example (retrieving what a word means from your mental lexicon) is a well studied construct that explains your answer ($f vs. $first_name) with the word superiority effect. I am looking for constructs like this! $\endgroup$
    – cessor
    Apr 19, 2013 at 8:10

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.