5 minimums for any perl script?

[Smylers]

Leo Lapworth writes:

> I've been asked what would be a good minimum to have as a coding
> police for a company that isn't focused on Perl, but uses it
> occasionally.

Hi. Thanks for posing such an interesting question, Leo, and for
everybody who's contributed answers -- it's been useful to see the
variety of views on this.

When I contemplated it the coding policies I most care about a Perl dev
team following turned out to be not very Perl specific:

  1 Make lots of small commits, one for each separable bug, feature,
    refactoring, or whatever, and clearly described as much: make a
    commit whenever you have something which is an unambiguous
    improvement on the previous state, however small. ("Unambiguous" cos
    if adding a feature has temporarily broken a different one, that's
    not an improvement to somebody using the other feature; don't commit
    till you've sorted it out.)

  2 If a database is involved, spend time thinking about the table
    design, preferably several of you together before any code is
    written. Make sure that it represents what it is you're actually
    storing.
    
    A poorly designed database forces all code that accesses it into
    awkward contortions to sort things out; it pretty much precludes you
    from ever writing clean code. Whereas if the database design is good
    but the code lousy, it's much easier to later clean up the code.

  3 Don't hard-code host names, absolute file paths, or similar. Always
    find a way of making them relative to the current server or
    directory, so that it's easy to check out multiple instances of your
    codebase and run them.

  4 When designing classes try to make each class be a noun which
    actually exists in the business requirements, not a made-up concept
    that's an artefact of a particular implementation. Try to make
    mutators be verbs that exist in the business requirements, rather
    than nouns which are attributes of the class.

  5 Keep code under 80 characters wide. While this seems like a trivial
    issue, when I've encountered lines that are hundreds of lines long
    they also seem to suffer other issues, so forcing people to break
    lines up might make people think about them and the readability of
    the code a bit more.

    Shorter lines also generally diff more nicely.
    
Those might be useful if you mean that the team in question only
occasionally do any development at all (and happen to use Perl for it).

But if it's a team of full-time developers who are adept at programming
in other languages but only occasionally use Perl then they're probably
on top of that kind of thing already and some more Perl-specific advice
would be better.

What'd be most useful to them depends which other languages they are
most familiar with, and what level they've reached with Perl. (For
example in many places use strict and use warnings goes without saying,
quite literally: it doesn't need to be said in a coding policy cos
everybody's doing it anyway.) But here's a go:

  1 Write your Perl in a way which maps to the business requirements as
    closely as possible.
    
    Perl is a very expressive language, allowing you more freedom than
    most in how you express a particular instruction. For example, map,
    grep, statement modifiers, and regular expressions built into the
    language offer ways of expressing things not found in some other
    languages. Use this to your advantage, so that it's easier to see
    that the requirements and their implementation match.

  2 Look on Cpan for everything.
  
    If you think a task is in any way common or might have been done
    before, check Cpan. Bother to install Cpan modules even for fairly
    small things which might not seem worth the hassle of installing a
    module -- because doing so means the module is then installed and
    available for use by other programs you write in the future too, and
    collectively it is worth it.

    For example it may not seem worth installing List::AllUtils just to
    avoid writing your own max function, but if you do install it then
    you have a handy library of common functions available.

    And if you use cpanm to install modules it isn't much hassle any
    more anyway.

  3 Use strict and warnings, and act on them.

    If you get a warning, find out what it means. Then either fix the
    issue or (if you've determined it isn't actually an issue)
    deactivate the warning for that part of the code, with something
    like:

      no warnings qw<uninitialized>;

    Don't get into the habit of putting up with 'ignorable warnings'
    which you're used to seeing scrolling past, and therefore
    potentially missing new ones.

  4 Design for testability.

    It can be awkward to graft tests into some Perl code which wasn't
    designed with testing in mind in the first place. So think about
    testing from the start, even if you write your tests later or don't
    test everything.

    In particular, don't bury things which should be easy to test in the
    middle of something else which is harder to test.

    To be even more specific, whenever you have an algorithm which
    calculates or processes something, separate that out to have an API
    which can be called directly by a simple command-line program. Don't
    have it so integrated with the application's input and output that
    the only way of testing the algorithm is to run the entire
    application, having to pretend to be a user.

  5 Use FindBin::libs (or similar).

    Be able to put modules in a lib/ subdirectory and have your code be
    able to find them without hardcoding the full absolute path, so that
    you can have multiple copies of your codebase, each self-contained
    and running independently.

Cheers

Simon