• How to: Document your code

    I have one rule to documenting code:

    1. Why, not what: Explain why the code is doing what it's doing, not what it is doing.

    Clearly this doesn't apply to code that is an API of some kind, where the code is the interface. Everywhere else, though, where the code is a mechanism to get the front-facing work done, explain the decisions that went into making the code do what it is.

    Some hypothetical examples:

    # Use port 3000 instead of 80 because that's what
    # Corporate is allowing us to use through the firewall.
    # Force this column to be a bigger font for Stan in Accounting.
    # Use Imager instead of Image::Magick because of
    # incompatibilities with frongdoodle mode in PNG images.
    # Can't use a JOIN here because MySQL 5.0's optmizer
    # makes a bad plan.  This is supposed to get fixed in 5.1.  See
    # http://wiki.mycompany/MySQL_optimization_problems for the details

    Note how all these examples explain something that may be out of the ordinary, or make the next reader (maybe even you) think "What the hell was this guy thinking?" A well-placed, well-written, well-thought-out comment will make the reader say "Aaaah, THAT'S why it's like that!"

  • It's Christmas in Perl-land

    Every year at this time brings the Perl Advent Calendar, 24 days of great new modules for you to know about. But what's this? This year the Perl Advent Calendar seems to have trouble starting up. They're looking for submissions for this year's calendar, and since it's already December 3rd, get on it!

    In the mean time, the Catalyst team have put out their own Catalyst Advent Calendar with 25 days of Catalyst tips. Catalyst is "the elegant MVC framework" and has quite a bit of traction. Their website is certainly better looking than your average Perl project website.

    Finally, PHP guru and all-around swell guy Chris Shiflett is running his own advent calendar focusing on a different member of the PHP community, and tips and tricks from that person. It's really nicely done. I'm also coveting the formatting for his code blocks. I'll just add "steal code block CSS from Shiflett's site" to the extremely long Perlbuzz.com to-do list.

  • BBC creates Perl On Rails

    The British Broadcasting Corporation has long used Perl, but:

    For applications that run internally we use Ruby on Rails. Because we enjoy using it, it's fast to develop with, straight forward to use and because we use it (i.e. to reduce knowledge transfer and training requirements) we decided to follow the same design patterns and coding conventions used in Rails when we built our MVC framework. Yes that's right we've built Perl on Rails.

    I know Curtis "Ovid" Poe is working for the BBC now, so here's hoping some of that Railsy goodness comes back to feed the community. The BBC already has 17 distributions on the CPAN.

  • Who's making bogus web requests?

    Yesterday I noticed in my Apache access log a lot of 404s that looked like this:

    aaa.xx.65.186 - - [25/Jul/2007:05:55:05 -0500] "GET http://www.some-advertising-site.com/banner/digits HTTP/1.1" 404 305 "http://some-different-website.com/" "legitimate-looking agent"

    Not only am I not hosting banner ads, the GET request is invalid. It should be GET /banner/digits..., without the scheme and hostname part of it. I wondered how many I had of these, and how many hits I was getting. A Perl one-liner to the rescue!

    perl -MData::Dumper -nae'++$n{$F[0]} if /GET http/; 
    END{print Dumper%n}' access.log
    $VAR1 = {
    'aaa.xx.65.186' => 132, # Real IPs obscured
    'bb.yyy.7.60' => 48,
    'ccc.zzz.46.147' => 111,
    'dd.qq.71.82' => 33

    So it looked like I was getting hit by a couple of 0wnz0red boxes with some sort of virus on them. I added them to my iptables DROP list and was done with it.

  • A roadmap for Perl 6 and Parrot

    Patrick Michaud, bless him, has produced for Perl 6 and Parrot what it's needed for a long time: A roadmap for future development. (Note that the link points to the Subversion repository for Parrot, and may be moved over time.) It's well worth reading, especially if you're wondering what Parrot and Perl 6 are all about as far as implementation and development.

    Key tech points for those not into reading so much:

    • Pugs is the Perl 6 on Haskell implementation being used to work out the language itself
    • The Pugs repository will be the home of the "official Perl 6 test suite" for now, and will be reorganized to make sure it reflects the current Perl 6 spec.
    • The Perl 6 compiler has four components
      1. the parsing grammar
      2. some parsing support subroutines
      3. the AST (Abstract Syntax Tree) transformation
      4. runtime support
    • Parrot 0.5.0 has a new object model that eliminates many obstacles in compiler work
    • Larry has written a standard grammar for Perl 6, and the compiler will be reworked to align with it
    • NQP is "Not Quite Perl 6", a lightweight version of Perl 6 for bootstrapping the language. Most of the Perl 6 compiler will be written in NQP.

    Best of all, there's a big section called "How others can start hacking and contributing," with clear instructions for interested bystanders who want to jump in. Too often on projects I see current participants not realize that there may be a perceived barrier to entry for outsiders, and Patrick has done what he can to eliminate it.

    I love love love it. Thank you, Patrick. I hope this article helps pick up some interest from those who have not yet joined.