Make no mistake about it. Perl code has a reputation for being ugly and hard to maintain. This reputation has been earned by years of programmers hacking out the code that gets the job done. There isn't anything wrong with this. You don't need to use double spacing, one inch margins, and a grammar checker if you are making a laundry list. The problem is that your Perl laundry list may continue to be used and referred to for months or years to come.

It doesn't have to be like that. People who really know Perl understand that it is a very expressive language. Perl can be used to state your thoughts cleanly and clearly. The same language that is used to make a laundry list is also used to make "The Catcher in the Rye". Some folks write poetry in Perl, for crying out loud! I usually aim for more of a "Green Eggs and Ham" kind of vibe, but maybe that's just me.

This meditation is intended to provide a few straightforward hints and habits to bear in mind in the quest to make Perl readable. They aren't solid rules, and I honestly don't follow them all the time myself. That's really why I'm writing this article: to remind myself that I can make my life easier by exposing myself to code that is already out there in the big wide world.

So without further ado ...

Read About Common Guidelines.

perldoc perlstyle is a good starting point for questions of code style and legibility. It's as close as we get to an official declaration of what good Perl might look like, although Larry Wall would probably never be so bold as to state that this is what good Perl should look like. As benevolent dicators go, he ranks as much more casual than the average. Still, keep the perlstyle guidelines in mind, and most people will be able to read what you write and have a good idea what your intent is.

"Regular" languages are good for more than a source of analogy and comparison. The single most useful programming book I have read in the last three years is Strunk and White's "Elements of Style". It has a lot of good common sense guidelines related to communicating with the written word. Perl (along with the other very high level languages) is still the written word, despite all the numbers and funny symbols.

Read Other People's Code.

Do you want to learn how to write code with good style? You want to look at as many samples of code as possible. Not just the good stuff, either. Look at good code, look at bad code, look at deliberately obfuscated code. Look at code written by deranged mutant gerbils from Dimension X. You need to understand why bad code is considered bad code. You also need to get past the urge to perceive all Perl code as bad code. I honestly believe that the only reason people consider Perl unreadable is the fact that they haven't sat down and read enough of it. Written English was confusing and bizarre to me when I was a child. ("I before E, except after C. What about 'weird'?") Okay, it's still a little bizarre to me, despite the fact that it is my native tongue. Now, though, I understand more of the subtleties that can be expressed with the right combination of vocabulary, expression, and context.

Perl is the same way. Learn the language. Read it like you would read a book or a magazine. You will get a better idea why most of us are told to use strict. At the same time you'll see why some people complain about how strict just gets in their way, and the steps they take to make assurances that their code is clean and solid.

Except, you know, when they don't want it to be clean at all. We call that "art".

Read Your Own Code.

It isn't as silly as it sounds. You want to revisit your code for a few reasons. First, you will be able to see what you've learned since the last time you saved that file. Second, it will encourage you to write cleaner code, because you know that you will be looking at it again. Third, it gets you ready for the next good habit.

Let Others Read Your Code.

This is scary, and the hardest advice for me to follow. I get attached to my code, and feel a sense of ownership. "This is mine, and I don't want somebody else telling me what's wrong with it." You know what, though? I need to get over it, and so do any of you that share my delicate geek ego. The fastest way to learn what you're doing wrong is to get a fresh set of eyes on your code. For that matter, it's also the best way to get an honest appraisal of what you're doing right.

I'm not telling you to go out and start pair programming. It might not be a bad idea, but it's not the same as what I'm suggesting. Most of these habits don't relate to methodologies for building software. They are about looking at code as language or literature. Again: the best argument against "Perl is unreadable" is to spend more time reading it.

Wrapping it up.

People complain constantly about the readability of Perl code. I think that this can be fixed by reading more Perl code to get a better understanding of Perl as a language (as opposed to Perl as a notation for expressing algorithms). There is definitely more to cover (perldoc, CPAN, etcetera), but I think that the simple act of reading can do a lot to enhance both the readability of what you produce and your appreciation for what can be written in this language.

Replies are listed 'Best First'.
Re: Note to Self: Read More Perl
by spartan (Pilgrim) on Apr 29, 2004 at 20:35 UTC
    ++ on "Let others read your code"
    There are PLENTY of good folks here that will critique your code for you. The key is to not take it too seriously. It's often not a personal attack, and folks can be VERY passionate about THEIR way. You know what they say about advice? Take it or leave it, it's free.
    So take what others have to say, see if it fits into your way of thinking and have at it. Keep learning along the way, and you can't help but pick up good habits.

    Very funny Scotty... Now PLEASE beam down my PANTS!
Re: Note to Self: Read More Perl
by perrin (Chancellor) on Apr 29, 2004 at 19:20 UTC
    At the risk of repeating myself, the book Perl Medic by Peter Scott has really good advice about style issues.
Re: Note to Self: Read More Perl
by demerphq (Chancellor) on Apr 30, 2004 at 09:16 UTC

    A good thing to try is to run perltidy over your code with various settings. Find a setting that you like and apply it regularly to your code. It keeps the style consistant which in the long run makes it easier to manage. Its defaults are also IMO fairly well chosen, so you arent going to annoy too many people if you just go with them.

    Although I recognize this is a different use of style than you meant, i thinks its worth keeping in mind.

    BTW, sometimes its worth recognizing that some tasks are always going to look ugly. Its hard to do much with a spec that is riddled with special cases and exceptions. So sometimes when the code looks ugly, well, there may be good reasons for it :-)


      First they ignore you, then they laugh at you, then they fight you, then you win.
      -- Gandhi

Re: Note to Self: Read More Perl
by EdwardG (Vicar) on Apr 30, 2004 at 08:00 UTC


    In 1918 Willam Strunk Jr. wrote the "little book", The Elements of Style, which is now recognised by The Modern Library as one of the "top non-fiction books of the 21st century" (it ranks at 21/100).

    The book is about style; getting to the point, not using unnecessary words, writing plainly.

    The book was first printed privately, for use in an English Usage and Style class, but reprinted in 1920 and published as a trade edition.

    Elwyn White, a student of Strunk, revised the Elements in 1959, adding a new chapter, An Approach to Style, and updating much of the material.

    Since White's revision, the book has become known as simply Strunk and White.

Re: Note to Self: Read More Perl
by Ninthwave (Chaplain) on Apr 30, 2004 at 13:05 UTC
    A comment on read your own code.

    Sometimes when going back to old code I scratch my head at why I did what I did. From this I learned to always cite example code I used as a basis for what I was doing even if the end code deviated radically from the example code. And I have now made it a habit of reading my own code periodically on working programs. I have sometimes had to rewrite working scripts to add better comments and better methods because I have learned to do things better over time.

    I think that has been the best in helping me with my code is to never let working code lie.

    "No matter where you go, there you are." BB
Re: Note to Self: Read More Perl
by flyingmoose (Priest) on Apr 30, 2004 at 14:11 UTC
    deranged mutant gerbils from Dimension X
    <DaveBarry> ... would be a great name for a rock band </DaveBarry>

    I've learned the most about quality coding (not algorithms and fancy stuff, per se, just coding in general) from watching others screw up, not neccessarily here, but work, college, etc. You learn about writing maintainable clean code, code that you can understand 2 weeks later, the difference between meaningful and useless comments, etc. Sadly, it seems that many others don't gather this information, since they don't read code with their eyes open ... nor do they think more than a few hours in advance when writing code. These people need to be flogged :)

    Also to be stressed is the fine line between idiomatic and transparent. They are not always the same, and given the choice of the two, I'll pick the later. map for instance is sexy, but if I want readability, often foreach takes a few less seconds to skim through, and that is pretty darn important. The alternative, of course, is equally dangerous, which brings me to the following anonymous quote: "Java is readable ... like a phonebook". That is, yep, you can read it ... but due to volume and verbosity, you really can't make any sense of it.

    in all, it's all about fine lines and tradeoffs, the "right way" cannot be codified -- ever -- and thus is coding as art -- a Zen state seldom attained in purely mechanistic cube farm engineering -- the drones will attempt to list style rules, but they'll never understand the why of the style, nor will they know when to break with the rules.

OT: White of Strunk and White (was: Note to Self: Read More Perl)
by Anomynous Monk (Scribe) on Apr 30, 2004 at 01:35 UTC
    The single most useful programming book I have read in the last three years is Strunk and White's "Elements of Style".
    All White's writing is lovely; for a special treat, there are audio tapes available of him reading his own works (at least Charlotte's Web and The Trumpet of the Swan). Much of the humor in these "children's" books isn't actually accessible to children; ironic statements that have me rolling on the floor pass completely over their heads.