"It may be trivia, but it's an important kind of trivia"1

Publications Sabotage Readable Code
© Conrad Weisert, Information Disciplines, Inc., Chicago
28 January, 2002

NOTE: This document may be circulated or quoted from freely, as long as the copyright credit is included.

Ever since the "structured revolution" of the 1970s we've paid close attention to the readability of source code. Programs that are hard to read are expensive and error-prone to maintain. Enlightened courses and textbooks present criteria for white space, indentation, alignment, commentary, data naming, and other aspects of readability. We expect programmers, from beginning students to experienced superstars, to comply with the spirit of those criteria.

It's surprising and distressing, therefore, that leading professional publications and trade journals continually undermine good practice in source code formatting. Particularly egregious offenders include:

Unreadable code in periodicals is often the result of trying to jam a program listing into a 3-column page layout. Each column is about 2 inches wide, enough for just 26 positions of monospace type. Squeezing code into 26-position lines may work for uncommented assembly language, but not for non-trivial code in any higher-level language.3 Imagine writing a program using an editor or a compiler that limited the line size to 26 characters!

Here's a recent example: 

class UseHello {
  public static void main
(String[] args) {
   HelloWorld myHello =
new HelloWorld();
   myHello.printHello();
  }
}

Communications of the ACM, vol. 44, # 10, p. 130

Worse yet is this one, where an identifier has gotten hyphenated: 

public class Greeter {
  public Greeter (String greet-
ings){
     greet = greetings;
     date = new Date();
}

Communications of the ACM, vol. 45, #2, p. 12

A wider 2-column (3½ inch) format is usually satisfactory, but it can yield hard-to-read, even illegal code when the author/editor fails to pay attention to the line lengths. This one not only violates indentation but also breaks string literals: 

               /* Here we construct a file request string.  Since we
are using
                  * a HTTP server, we need to simulate a file
request.  We do this
                  * like: GET /filename HTTP/1.0\r\n\r\n
                  * Notice that two  ctrl/lf sequences are needed at 
the end of the request
                 */
                  String requestString="GET /"+ theFile.getText()+"
HTTP/1.0\r\n"+"\r\n"
                  theHTMLCode.appendText("\n The Request String
is:\"+requestString);
                  outStream.writeBytes(requestString);

Java Developer's Journal, vol. 2, #4, p.55

As a result of these strange practices:
  • I no longer submit to those publications articles or even letters to the editor that contain source code examples.
  • I don't distribute to students4 reprints of such material.
  • I stop reading many items as soon as my eye gets confused by bad layout.

I still expect readable code from students and project-team members, and write readable code myself.

Magazine editors: NOTE

Three-column format is inappropriate for material containing program source code. If you must set the text in three columns, then move the code examples out to figure boxes.

And no matter what line length you choose, make sure the line breaks occur in logical (or at least legal) places.

Your publication is about computer programming. Have a competent computer programmer proofread it.

1 -- Overheard at a 1965 SHARE meeting following a discussion of compatibility prolems in IBM's OS/360.
 2 -- Source-code misformatting is far from the only editorial problem plaguing that once-prestigious publication. Hardly an issue lacks some gaffe in grammar, usage, terminology, or fact.
 3 -- The C/C++ Users Journal also relies on 3-column format for some material. However, the editors pay more attention to the line breaks, use a smaller font, and are willing to switch to two columns in the middle of an article when the material demands.
 4 -- Even if the students were able to decipher the code, what message is conveyed to them by a respected international publication violating practices their instructor has told them are important?

Return to IDI Home Page
Return to Technical articles

Last modified January 28, 2002