Line Length, Volume, and Density

By | March 9, 2008

Update: This entry seems to be getting a lot of new attention; welcome! The lessons of line length, volume, and density, along with lots of other good design principles, are applied to the Solar Framework for PHP 5. Be sure to give it a look if you’re interested in well-designed PHP code.

When it comes to coding style, there are are various ideas about how you should write the individual lines of code. The usual argument is about “how long should a line of code be”? There’s more to it than that, though. Developers should also take into account line volume (“number of lines”) and line density (“instructions per line”).

Line Length

The PEAR style guide says lines should be no longer than 75-85 characters. Some developers think this is because we need to support terminals where lines may not wrap properly, or because some developer screens may not be big enough to show more than that without having to scroll sideways, or because it’s tradition, and so on. These reasons may even be accurate in some sense. However, I see the 75-character rule as recognizing a cognitive limitation, not a requirement that can change with available technology.

How many words per line can a person scan, and still be able to grasp the content of the line in the context of the surrounding lines? Printing and publishing typographers figured out a long time ago that most people can read no more than 10 to 12 words per line before they have trouble differentiating lines from each other. (A “word” is counted as five characters on average.) Even allowing for a 25% to 50% increase, that brings us up to 15 words. Times 5 characters per word, that means 75 characters on a line.

So the style guide limitation on line length is not exactly arbitrary. It is about the developer’s ability to effectively scan and comprehend strings of text, not about the technical considerations of terminals and text-editors.

Line Volume and Density

Some developers believe you should put as much code as possible on a single line, to reduce line-count. They say this makes the code read more like a “sentence”. In doing so, these developers trade line “volume” for line “density” (or line “complexity”).

Increasing the density of a line tends to make it less readable. Lines of code are generally lists of statements, not natural-language prose. If you put a lot of instructions on a single line of code, that tends to make it harder for other developers to decipher the logical flow.

Examine the following:

list($foo, $bar, $baz) = array(Zim::getVal('foo'), Dib::getVal('bar'), Gir::getVal('baz', Gir::DOOM));

(Yes, I have actually seen code like this. Only the identifier names have been changed.)

Now compare that to the following equivalent code:

$foo = Zim::getVal('foo');
$bar = Dib::getVal('bar');
$baz = Gir::getVal('baz', Gir::DOOM);

When I showed this rewrite to the initial developer, his complaint was: “But it’s more lines!”.

Increasing line volume (“more lines”) and reducing line density does three things:

  1. It reduces line length to make the code more readable.

  2. Making it more readable makes the intent of the code more clear. The logical flow is easier to comprehend.

  3. In this particular case, it may be faster than the original one-liner, because it drops the list() and array() calls. True devotees of the Zend Engine will be able to say for certain if this translates into faster bytecode execution. (I am not a fan of speed for its own sake, but in this case it would be good gravy over the meat of the above two points.)

In reducing line density, you don’t have to make one line correlate with a single statement (although usually that’s a good idea). Here’s another way to rewrite the original example, this time as a single statement across multiple lines:

list($foo, $bar, $baz) = array(
    Zim::getVal('foo'),
    Dib::getVal('bar'),
    Gir::getVal('baz', Gir::DOOM)
);

I find this less readable than the initial rewrite, but the principle is the same: more lines, but shorter, to improve readability.

Balancing Considerations

If shorter lines are better, does that mean lines should be as short as technically possible?

$foo
=
Zim::getVal(
'foo'
);

$bar
=
Dib::getVal(
'bar'
);

$baz
=
Gir::getVal(
'baz'
,
Gir::DOOM
);

It looks like the answer is “no”. The line-volume vs. line-density argument is about readability and comprehension. The above example, while absurd, helps to show that overly-short lines are as difficult to read as over-long ones.

Developers with good style balance all the considerations of line length, volume, and density. That means they write lines of code no more than about 75 characters long, but not so short as to be increase line volume without need. They also show attention to line density for reasons related to cognition and comprehension, not merely technical syntax.

44 thoughts on “Line Length, Volume, and Density

  1. Helgi Þormar Þorbjörnsson

    I couldn’t agree more with this, there are number of projects where I’ve been coming in on late stages (open source and corporate alike) where I’ve beefed up their coding standard and namely this part, line lengths, the flow of the code and amazingly everyone started to understand the code in a jiffy where in the past it was considered a PITA to explore forgotten code.

    This rule + return errors early, i.e. not doing

    if (!isError()) {
    do all the fun stuff;
    } else {
    return error:
    }

    do;

    if (isError()) {
    return error;
    }

    do fun stuff;

    It’s just mind blowing how much more understandable the code becomes if you just follow the 75-85 char rule and return errors early rule

    Good post!

    Reply
  2. Rob Young

    Nice post, well said. Helgi, that’s very similar to what I was told early in my career. The smallest side of a conditional block go first so that your eye doesn’t have to train over a large amount of code to find the other side of the condition. So rather than

    if (condition) {
    lots and
    lots and
    lots of
    code
    } else {
    a little code
    }

    do

    if (condition) {
    a little code
    } else {
    lots and
    lots and
    lots of
    code
    }

    Reply
  3. Nigel James

    Great post Paul. I think you hit the right balance and for good reasons.

    Whitespace and more lines make for readable code so while you can do this:
    for($i = 0, $max = sizeof($myarray); $i < $max; ++$i) {}

    i find this more readable
    $max = sizeof($myarray);
    for($i = 0 $i < $max; ++$i) {}

    Personally I dislike have to scroll way to the right to have to find the end of a line of code.
    Cheers,
    Nigel

    Reply
  4. Pingback: PHPDeveloper.org

  5. Brian

    I’ve been reading Steve McConnell’s “Code Complete” and he really has a lot to say about this. The longer I’ve been working in the software world, the more I’m convinced that readability (and therefore maintainability, etc) are far more important than speed or “cleverness.” This is especially true if you’re having to work with multiple languages.

    Reply
  6. blog.ekini.net

    i feel guilty about writing “dense code”…. thanks for the reminder. although i can understand my code – comments, etc… others might say otherwise if they read my code.. again, thanks…

    Reply
  7. Pingback: Paul Jones’ Blog: Line Length, Volume, and Density | Cole Design Studios

  8. Pingback: Lunghezza, volume e densità: questione di stile : php5blog.it

  9. Speed Vs Readability

    Hi,

    This is a good post in terms of ‘Readability and Maintainability’. But no idea of speed related issues. In high traffic applications, code refactoring done to improve performance/speed when cpu hitting the roof(Post Production).

    Here is sample:

    if(isset($name)){
    echo ‘Mr’.$name;
    }else{
    echo ‘Name missing';
    }

    Five lines of code – More volume and less density
    ———–
    The same is written as:

    echo isset($name)?’Mr’.$name:’Name Missing';

    Only one line of code – More density and less volume.

    Which is good in terms of ‘speed’?
    Which is good in terms of ‘Readability and Maintanence’?

    Reply
  10. Pingback: PHP Weekly Reader - May 16th 2008 : phpaddiction

  11. Jyot Vakharia

    Hi,
    I have been dedicated to PHP development for a while. As far as the coding standards are concerned, I am pretty happy that there exists some standard, which regulates how the code appears. Nevertheless, I am a bit skeptical on the effect of the standard following on the performance of the script. Addition of spaces instead of tabs makes the code only long. Though I might be wrong, when it comes to loading the same script a thousand times, it should effect the performance of system. Correct me if I am wrong though.

    Thanks

    Jyot Vakharia

    Reply
  12. pmjones Post author

    Hi Jyot —

    The addition of whitespace (and comments!) does **not** affect performance significantly. (Yes, that came as a surprise to me, too, when I first heard it, but it is true.)

    Even better, when you use a bytecode cache, the whitespace and comments are not retained in the bytecode, so they have zero performance impact at that point.

    Reply
  13. Pingback: Coding standard, coding style | Kristian Lunde

  14. Izkata

    How could whitespace and comments affect code? It’s all stripped out before it gets compiled, and doesn’t exist in the program itself.

    Reply
  15. Anthony Gentile

    Re: Speed vs Readability:

    The ternary is actually more opcodes than the if else block. Ternaries are nice for that one liner, but make it much more difficult to understand what is going on…especially when they are nested (please dear lord no). Honestly…if you are doing super duper millisecond optimizations…you are probably not spending your time very well. Unless you are working on a heart monitor or some other critical application that requires some unreadable cleverness(comment it)…go with readability.

    Reply
  16. Marcus Bointon

    Another factor that contributes to the poor readability of long lines is that many editors have utterly useless soft line wrapping, giving you a non-choice of trashed indenting or horizontal scrolling (emphasised by wasteful single-window UIs). Eclipse and Netbeans fail completely, and even the almighty vim makes a mess of it (though there’s probably a patch…). BBEdit does it beautifully; lines can be as long as you like, and indenting is preserved dynamically. This is especially useful when you’re dealing with files that need long lines, such as CSV or SQL dumps, but you want to do without the pain of horizontal scrolling. Another fly in the ointment is the annoyingly persistent IE6, which doesn’t handle whitespace in HTML properly, necessitating long lines on occcasion.

    I find it completely bizarre that such a basic feature of text editing is missing in so many editors. The tabs vs spaces thing falls into the same camp; 1 indent = 1 tab makes total sense, and using multiple spaces doesn’t, yet we’re stuck with it because editors are randomly crap and lowest common denominator prevails.

    This doesn’t necessarily have anything to do with deliberately restricting line lengths for the sake of readbility – sometimes I find that splitting lines unexpectedly makes things harder to read – especially if peculiarly indented. There’s clearly a balance to be struck for readbility (the point of this article), but it should be for the benefit of people, not their possibly inept tools.

    Beyond that, I also find it strange that more editors can’t enforce/apply coding standards automatically. It could save a lot of time wasted on formatting that could be spent coding.

    Reply
  17. Garrett W.

    Marcus: The [very] few times I’ve worked with Visual Studio, I’ve noticed that it enforces coding standards more than any editor I’ve seen.

    Reply
  18. John S.

    I agree with most of this, with one notable exception: comments. I typically follow a convention of:
    1) Comments applying to a block of code go above, and
    2) Comments applying to a single line go to the right.

    Cognitively, I perceive a code/comment line as two statements, so based on his 75 character cognitive limit, that would actually give a line length of 150 characters. (75 for the code and 75 for the comment.) I especially find this convention easier to read with properties.

    For example:
    //This property does some really important stuff.
    public $myProperty1;

    //This property isn’t so important.
    public $myProperty2;

    is harder to read than:
    public $myProperty1; //This property does really important stuff.
    public $myProperty2; //This property isn’t so important.

    Reply
  19. John S.

    Another thought occurred to me: the cognitive limit probably only applies to occupied space, not white space.

    In other words, a deeply indented line that contains 65 spaces and 18 alphanumeric characters would be perceived by a human as 18 characters, but by a computer as 83 characters. Perhaps code formatting utilities should ignore white space?

    Reply
  20. Pingback: PHP PEAR ??????? | { yeah : ??? }

  21. Pingback: Paul M. Jones » Blog Archive » Regarding Underscores

  22. Paula Parisi

    Paul,

    This is an amazing piece of writing, in terms of its functionality and with high points for literary style! As a traditional “writer” by profession, who is just learning php, this type of well-reasoned and grammatically-inclined approach is exactly what I was craving (and having a very hard time finding. I wound up following an electronic breadcrumb trail to your site starting with a link in the book “SAMS Teach Yourself PHP in 10 Minutes,” that led to pear.php.net). I will be devouring every word on your site!

    -Paula Parisi

    Reply
  23. Felds

    I think that

    $aLongAndDescriptiveObjectName->anotherLongAndDescriptiveName($inputParameter); // 80 chars

    … is way more readable than

    $a->b($c); // 11 chars

    I’ve seen this happening a few times.
    Limiting the line lengths sometimes brings more problems than solutions.

    Reply
  24. Oliver

    @Felds
    try this:

    $aLongAndDescriptiveObjectName
    ->anotherLongAndDescriptiveName($inputParameter);

    It looks strange but you get used to it. Most of my constructors look like this:

    $this
    ->setFoo($foo)
    ->setBar($bar)
    ->setBaz($baz);

    And if your object model is good you hardly need really long names.

    $h = $fooBarBazGirGumpWhatever->getHandles();
    $h->barzoinkadings->close();
    $h ->wallawallahoi->close();
    $h->redoplasma->close();

    is more readable then

    $foo->getBarzoinkadingsHandle()->closeHandle();
    $foo->getWallawallahoiHandle()->closeHandle();
    $foo->getBarzoinkadingsHandle()->closeHandle();

    Reply
  25. Daniel O'Connor

    I think one of the mistakes we’ve made is expressing this as “75-85″ characters. You are dead right, it’s about word groupings.

    We all saw that “Cambridge University” jumbled words paragraph that got spammed around the internet.
    “I cnduo’t bvleiee taht I culod aulaclty uesdtannrd waht I was rdnaieg”

    If nothing else it really highlights that we can work on word shape alone.

    I’d love to try and express this differently, as “avoid lines longer than x words” or “Avoid having more than X words over Y characters long”. Or at the very least; having trim()’d the preceeding whitespace avoid having a line < 85 characters.

    Reply
  26. Moto Akumulator

    Steve McConnell’s “Code Complete” is essential reading on this topic. I need 3 years to put his ideas in my programers practice but today when i looa at my code i am sure that anyone who comes after me will have easy job . Principles of coding from his book shuld be mandatory for any programer !!

    Reply
  27. Pingback: On Preferring Spaces Over Tabs in PHP | Paul M. Jones

  28. Pingback: W3C Notes One Of My Posts As An “Informational Resource” | Paul M. Jones

  29. Nicolas Dermine

    I also found my code getting better and better by conforming to an 80 characters limit (less duplication, better named variables and methods).

    Another advantage that I noticed lately is when looking at SVN diffs : having lines under 80 characters allows me to see the two revisions side by side without having to scroll to the right to see what changed.

    Reply
  30. Pingback: [Erledigt] Coding Guidelines - php.de

  31. cartbeforehorse

    It seems strange to me to mention any line-character-limit at all.

    Does someone else agree, that much more intuitive than enforcing a strict character-limit, is to implement rules of thumb. Good examples of getting the balance right are mentioned in the main article, but also in later comments by Oliver, Helgi and John S.

    But I’d even go further than that, and simply say that:
    >> if it looks readable, it probably is
    >> if it doesn’t, then leave it for a couple of days, and if you can’t figure it out when you come back, there’s probably a better way…

    I also find that I don’t much care about line-length, assuming that the code which goes beyond the end of my editor, is only detail (e.g. a long list of arguments to a function). The descriptive part of code should be in the function name, not in the parameters. So for example I find this:


    $this->DoSomethingNicetohave ($param1, $param2, $param3, $param4,... param12);
    $this->DoSomethingEssential ($paramA);

    much more readable than:


    $this->DoSomethingNicetohave (
    $param1,
    $param2,
    $param3,
    $param4,
    ...
    param12);
    $this->DoSomethingEssential ($paramA);

    For me, the vertical spacing of the code is sometimes as important as the horizontal spacing, and in the above example, the fact that one function call takes up 13 lines, distracts from the fact that what is really important is the essential code.

    On a different but related subject, I find that a 4-space-indent is becoming very common as a coding standard. Is there any reason for this?
    I always learned to code with 3-speace-indents, and when I tried to switch to 4, I found myself (desperately at times) trying to win back those 7 or 8 characters that I lost in the indentation.

    Reply
  32. Detail

    Often it’s what the developer is used to. That’s what makes it easier for them to read, as individuals. Readability is the most important thing, and there’s usually a case for going too tight, or too far down (commenting, comes to mind).

    Having said that, there are always ridiculous extremes.

    Reply
  33. Geil Ficken

    Thank you for providing such detailed information for the Solar Framework. I´m in coding for some years now but this is completely new to me so I´m always happy to find some good information.

    Regards

    G. K. Ficken

    Reply
  34. Ginndee

    Paul’s article and comments make me realize my programming style.
    this is a wonderful discussion for a non-pro programmer…

    thanks alot guys..

    Reply
  35. kulturystyka sklep

    i feel guilty about writing “dense code”…. thanks for the reminder. although i can understand my code – comments, etc… others might say otherwise if they read my code.. again, thanks…

    Reply
  36. Jez

    I think any line-length restriction (even recommendation) is overly prescriptive, and only likely to put people off a whole set of standards.

    Reply
    1. Eliptical view

      I agree. For certain code short lines makes sense. For other code very long lines makes sense, like if you are trying to line things up between a set of lines to easly see patterns. I’ve been programming since the days of the 40 and 80 character wide terminals, and am so glad that is gone and we have big and wide screens to work on.

      Reply
  37. Pingback: Unit 3: Justify the need to have coding standards and discuss the elements to be included in it. « karthikgowda12

  38. ukash bozdurma

    For certain code short lines makes sense. For other code very long lines makes sense, like if you are trying to line things up between a set of lines to easly see patterns. I’ve been programming since the days of the 40 and 80 character wide terminals, and am so glad that is gone and we have big and wide screens to work on.

    Reply

Leave a Reply

Your email address will not be published. Required fields are marked *