A half-century struggle continues . . .

Source-Code Readability Still an Issue!

by Conrad Weisert
May 1, 2011
© 2011 Information Disciplines, Inc.

This article may be circulated freely as long as the copyright notice is included.


It's hard to think of an issue in computing technology that has more stubbornly resisted solution than the readability of computer programs. Of course good programmers know how to write nicely-formatted well-commented code with well-chosen data names, and they've known how for decades. Nevertheless understandable source code remains more the exception than the rule in today's software development shops.

Furthermore many of those unreadable nightmare programs are being produced not by inexperienced beginners but by "senior developers" and by graduates of university Computer Science programs.

Why? What can be done?


In the 1960s a typical response from a programmer who had produced an unreadable nightmare was that his high-pressure project was so urgent that he didn't have time to worry about quality issues. He might promise to go back and tidy up the code once he had gotten the program to work.

I've recently (2011) heard exactly the same response from several experienced and well-regarded "senior" programmers! A couple of them expressed impatience and irritation that I would raise such an issue while they were desperately trying to meet a critical deadline.

Related information
on this web site

We've been noting this problem for some time. Earlier articles include:

Saving Time?

Most of the time the "trade off" between readability and time is an illusion. Experience has repeatedly shown that thoughtless plunging into coding not only leads to severe compromise in final code quality, but also, more often than not, actually costs time. The tired there-wasn't-time-to-do-it-right excuse is no longer accepted by experienced and knowlegeable managers.

Pride in obfuscation

In the early days a few misguided programmers actually took pride in creating code that defied understanding. Computer programming was itself a novelty then, and programmers possessed skills that, in popular perception, bordered on magic. Writing code that others couldn't understand reinforced their pride in working on the frontiers of advanced science.

The "structured revolution" of the 1970s put an end, we thought, to such silliness, but the recent proliferation of specialized platforms and overcomplicated protocols seems to have stimulated a revival of 1960s attitudes among those who take perverse pride in being members of an elite insider group.

I recently asked a young programmer to recommend a textbook on a new set of protocols for web-deployed interactive applications. He replied that there not only was no such textbook, but that he believed it would be impractical to try to write one! He claimed to have gained fluency in the techniques himself1 through long online interaction with the developers and members of a vendor-specific community.

Academic contributions

What grade should an instructor give to a student's programming exercise if the program produces the correct result and uses the prescribed algorithm? Although I always call attention in advance to my grading criteria in an advanced programming course, I nevertheless sometimes hear an outraged protest from a student who is astonished by his C. He may claim that in his entire academic experience he has never before been "penalized" for turning in a program that works.

That student believes that a program that works is supposed to get an A. He protests that it's unfair to "take points off" for aesthetic issues like readability. Unfortunately, the student may have a solid basis for his misguided belief:   grades in previous courses!

Of course, most computer-science instructors encourage and reward good practice from their students. Many of them, however, face such huge workloads that they lack the time to examine students' work in detail. Instead, they may fall back on using:
  • a grader, often a graduate student2 who lacks confident command or appreciation of judgmental criteria, or

  • automated validation.3

Further clarification—May 17

After I posted this little essay two weeks ago, a young reader wondered whether I really make clear to students that they're expected to produce readable code in their exercises. We might expect that any student who got to an advanced level would already know that, but to be absolutely sure, I start every intermediate or advanced programming course with an hour lecture based on these presentation slides.

Fortunately, the troublesome students almost always overcome their surprise and by the end of the course, with a little extra coaching, express their appreciation. Their future managers will also appreciate the results of that lesson.

1—In examining code produced by that young man, I was reminded of the 1960s obfuscators:   absence of introductory (context establishing) commentary, misleading data names, monstrously long lines. It was almost as if he were daring the reader to figure out his work.

2—I now always do my own grading, even if I'm offered a grader.

3—I actually saw this direction in another instructor's assignment:   "Link your module with this driver program, run it, and turn in the output."

Return to table of contents
Return to technical articles

Last modified May 17, 2010