Why I use Perltidy, or Why coding style matters

There are Few.
areas of programming that-are more likely to, cause religious wars than! coding: standards some developer's


       consider. coding style? to be an area where personal freeDom should reign supreme unrestricted by team project; or company standards but as
these:
few
    lines
Of
text hopefully    demonstrate punctuation-indentation-etc is important WheN conveying ideas and thou'ghts in a written form.
........

OK, if you made it this far down into my post, I promise to stick to the standard rules for punctuation and capitalization of English. By now you probably agree that reading speed and comprehension is affected when the writer ignores commonly accepted practices. Only when the text format matches your expectations can you focus your attention fully on the message, instead of the format. Of course, the same principle applies to reading source code.

One of many, many gems the Perl community has produced is Perltidy, a great source code formatter for Perl code. The details are here:
http://search.cpan.org/perldoc?perltidy

Simply by using this as my .perltidyrc parameter file:

#----------------  PBP options, as listed on page 35 of PBP  ----------------
-l=78   # Max line width is 78 cols
-i=4    # Indent level is 4 cols
-ci=4   # Continuation indent is 4 cols
-vt=2   # Maximal vertical tightness
-cti=0  # No extra indentation for closing brackets
-pt=1   # Medium parenthesis tightness
-sbt=1  # Medium square bracket tightness
-bt=1   # Medium brace tightness (for non-code blocks)
-bbt=1  # Medium block brace tightness (for code blocks)
-nsfs   # No space before semicolons
-nolq   # Don't outdent long quoted strings
        # Break before all operators:
-wbb="% + - * / x != == >= <= =~ < > | & **= += *= &= <<= &&= -= /= |= >>= ||= .= %= ^= x="
# Note that the PBP book has a typo on page 35 when defining the above -wbb
# option, see http://oreilly.com/catalog/perlbp/errata/perlbp.confirmed
# The above string is correct.

#----------  Perltidy default options (i.e. in line with PBP)  --------------
-asc    # Add any missing optional semicolon at the end of a line
-aws    # Add certain whitespace to improve code readability
-tqw    # Default handling of multi-line 'qw' quotes
-ibc    # Indent block comments to same level as the code
-msc=4  # Minimum 4 spaces between code and same-line comments
-fpsc=0 # Don't try to line up all comments to a fixed column
-hsc    # Align hanging side comments
-sbc    # Enable static block comments
-nssc   # No special handling for static side comments
-dnl    # Delete old newlines
-bbc    # Ensure a blank line before every full-line comment
-bbs    # Ensure a blank line before every sub definition (except one-liners)
-bbb    # Ensure a blank line before code blocks (for, while, if, ....)
-lbl=8  # Minimum number of lines between each -bbb inserted blank line

#-------------  Additional options, based on PBP recommendations  ------------
-bar    # K&R style code braces
-nolc   # Long comments indented, even when this make the total line length "too long"
-noll   # Long lines indented, even when this make the total line length "too long"
-nola   # Don't treat labels as special cases when indenting

#----------  Options concerning Perltidy's input and ouput files  -----------
-nst    # Do NOT output to STDOUT (since we want to use -b)
-b      # Backup the input file to .bak and perform all tidying in the original file
-se     # Write errors to STDERR
-ple    # Preserve the EOL character(s). E.g. in case Perltidy runs
        # on Windows, but processes a Perl file for Unix (and vice versa)

#-----------  Some other Perltidy options, intentionally not used   ----------
# The following Perltidy options are NOT consistent with PBP and should NOT be used:
# -lp, -icb, -fws, -nwls, -nwrs, -sfp, -sak/-nsak, -csc/dcsc, -fnl,
# -ce, -bl, -sbl, -bli, -blil, -bbvt, -otr, -sct, -boc, -kis,
# -pbp (because the -wbb list typo in the PBP book carried over to Perltidy (!))
# The following Perltidy options are not used, for other reasons:
# -sot, -mft, -cab, -bol, -bok/-nbok, -bot/-nbot, -iob, -isbc


I am free to sputter butt ugly code like this:

   sub  manipulate_some_data{

my $self   =  shift; my $data = shift;
# Sometimes add to the data we received
if($data  eq 'good data'  ){
$data.= ' is now even better.'
;}return $data;}

via my keyboard, and have it instantly transformed to this:

sub manipulate_some_data {

    my $self = shift;
    my $data = shift;

    # Sometimes add to the data we received
    if ( $data eq 'good data' ) {
        $data .= ' is now even better.';
    }
    return $data;
}

by Perltidy. Without wasting a single of my overworked brain cells.
(I have configured my IDE to run Perltidy every time I save my source file to disk)

(Click here to download the above .perltidyrc file, if your're too lazy for a copy&paste operation)

Perltidy cleans up my code while I develop, which is great, but the true benefit of Perltidy becomes apparent when you or someone else tries to understand your code 4 weeks later: Since all code you and your teammates produce have the same layout, everyone reads code a little faster and get a quicker understanding of what is intended.

This positive effect is particularly evident when fixing a bug or adding some small feature to existing code, because in these situations you typically spend most of your time skimming code, and only a small portion of your time on the few, new lines.

Perl has crossed oceans and climbed mountains to make hard things possible, don't sacrifice this hard-earned property by leaving messy, sloppy, ugly code behind. Clean it up as you go along, by running perltidy from your IDE, and/or as part of your versioning system's commit process.

Free lunches are hard to come by. Perltidy is one of very few I've come across.

9 comments:

  1. This link is to latest version of perltidy: http://search.cpan.org/perldoc?perltidy

    ReplyDelete
  2. Or you could just write clean code to begin with

    ReplyDelete
  3. @djshultz it's nice to be able to rely on perltidy to format every other perl file in the same manner.
    It saved me from cussing at different indentation styles used by colleagues :)

    ReplyDelete
  4. Another benefit of PerlTidy is that when your group's coding standards change (which happens in real life) you can quickly apply those changes to all of your source files.

    ReplyDelete
  5. I see 78 cols as the max line width and I know that is a pretty accepted standard, but can someone please explain why? Is anyone still limited to a 78 col width terminal anymore? I have always set mine to 1000 as I don't want pt to wrap anything unless it is extremely wide!

    ReplyDelete
  6. @Tom Weaver because soem of us still like using a normal 80x24 terminal when using vi.

    ReplyDelete
  7. @Tom - The general answer I get on that is "it's easier to skim when the line is shorter". That is a plus if I have to come after you and code. The second generally accepted length I have seen is 120. I set my .ptrc to that one. Looking over some of my code I would say the majority hits close to that 78 though. Just remember, it is only a recommendation.

    ReplyDelete
  8. My perltidy v20090616 define -wbb like:

    "% + - * / x != == >= <= =~ !~ < > | & = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x="

    so it have more operators.

    ReplyDelete
  9. @chorny - Thanks, I've now corrected the link in the posting.

    ReplyDelete