What should I put in my starter template for my Perl programs?

Question

I'm basing the majority on my Perl scripts on the following template/skeleton:

#!/usr/bin/perl -w

use strict;
use utf8;

$| = 1;
binmode(STDOUT, ":utf8");

# my code goes here.

The things achieved by this template:

1. Enable warnings (-w)
2. Enabling strict mode (use strict)
3. Going pure UTF-8 (use utf8 + binmode(STDOUT, ":utf8"))
4. Disable buffering ($| = 1)

My question is:

How can my template be improved to better reflect Perl best-practices?

Answer 1

Replace the -w with use warnings. It allows you to disable warnings lexically should you need to. See perllexwarn.

The use utf8 pragma is for when your source code is in UTF-8. If it is, great. If not... I don't recommend adding things that you don't actually use. Similarly, don't set STDOUT to UTF-8 unless you're actually producing it.

Disabling buffering will reduce performance. Don't do it unless you need to, and then limit the scope to the block where it's necessary.

I like to include a statement to explicitly state the minimum version of Perl required to run the script. This makes the error messages more meaningful if it doesn't compile due to someone using an older version of Perl. e.g.

BEGIN { require 5.00801 }

I use that particular incantation instead of something like use v5.8.1 because it's backwards-compatible with the versions of Perl I'm trying to "support" with a meaningful error message.

Answer 2

Not that it's something that can be achieved in a template as such, but you can enforce perl best practices by forcing developers to run perltidy and perlcritic on all source code. Furthermore perl best practices is a must read, if you ask me.

As for your template, the only thing you should consider changing are the parenthesis after the builtin binmode function, since they are not required (this is one of the many recommendations in the book).

Answer 3

How about throwing in some documentation?

=head1 NAME

name here

=head2 SYNOPSIS

short synopsis here

Answer 4

Change the interpreter line to

#!/usr/bin/env perl

This prevents you from using -w, so you'll have to also

use warnings;

Answer 5

Here's mine, although I must admit that sometimes I just start typing without using the template. I set it up as a modulino so it's easy to add testing to it later:

#!perl
package App::XXX;

use utf8;
use 5.010;

use strict;
use warnings;
use vars qw($VERSION);

$VERSION = '0.01_01';

__PACKAGE__->run( @ARGV ) unless caller;

sub run
 {
 my( $class, @args ) = @_;


 }

1;

If you want to set all of your filehandles to some encoding automatically, you could add the open pragma:

 use open IO => ':utf8';

I have another template for documentation that I add later.

Also, some people have editor sequences that they add as comments at the top or the bottom of the script. Perhaps:

# -*- Mode: cperl; coding: utf-8; cperl-indent-level: 4 -*-
# vim: ts=4 sts=4 sw=4:

Since I put my scripts into distributions, the installation process automatically fixes up the shebang line so it doesn't matter what I put there.

Answer 6

Another thing you may want to look at is the module Toolkit on CPAN. Created by Damian Conway it allows you to assemble a set of often used modules and then use a single 'use' line instead of several. So instead of

use strict;
use warnings;
use foo;
use bar;

You'd have;

use Toolkit;

and all of the modules you placed in your toolkit would be available.

Answer 7

I never use a shebang line in my .pl scripts, nor do I use use lib /path/to/special/lib, so as to allow these to be customized for each invocation:

perl -I/path/to/special/lib myscript.pl

/usr/local/perl5.10 -I/different/path/to/lib myscript.pl

And of course, every file starts with:

use strict;
use warnings;

Edit: I thought of a few more things, that I've started to use more recently:

# at least while the project is in initial development, so as to
# expose more places where the module might die; maybe turn off
# in production, depending on what other error handling is in place
use autodie;

# ...after all other 'use' lines at the top of a module: remove all
# unwanted imports cluttering up our namespace
use namespace::autoclean;

Answer 8

Although not everything Perl I do is for the web, it happens often enough that I am compelled to add:

use CGI::Carp qw(fatalsToBrowser);

to my development template, which I comment out once it hits production.

Answer 9

I'd say you want to be including a standard set of POD documentation in your template, with the normal set of headings that you see it most modules on CPAN. I like to include this at the end, but you might like it at the top or even interspersed through the code. e.g. at the end:

1;
__END__

=head1 NAME

My::Foo - The great new My::Foo!

=head1 VERSION

Version 0.01

=head1 SYNOPSIS

=head1 DESCRIPTION

=head1 METHODS 

=head2 new

=head1 AUTHOR

=head1 BUGS

=head1 ACKNOWLEDGEMENTS

=head1 COPYRIGHT & LICENSE

This program is free software; you can redistribute it and/or modify it
under the terms of either: the GNU General Public License as published
by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

=cut

I find writing my module as if I was going to release it to CPAN, even if I never well is a good idea. For more wisdom and best practice check out module-starter. sudo cpan Module::Starter. This handy little tool will build you a complete module skeleton, which is most instructive to browse through. e.g.

$ module-starter --module=My::Foo --author=markp [email protected] --mb
$ tree My-Foo

Answer 10

It doesn't make sense to me that you would want to, by default, turn off buffering.