view release on metacpan or  search on metacpan

lib/App/perlstyle.pod  view on Meta::CPAN

    $Minimum = 10;          # wrong
    $MAXIMUM = 50;          # right

Other variables are lowercase, with underscores separating the words. 
They words used should, in general, form a noun (usually singular),
unless the variable is a flag used to denote some action that should be
taken, in which case they should be verbs (or gerunds, as appropriate)
describing that action.

    $thisVar      = 'foo';  # wrong
    $this_var     = 'foo';  # right
    $work_hard    = 1;      # right, verb, boolean flag
    $running_fast = 0;      # right, gerund, boolean flag

Arrays and hashes should be plural nouns, whether as regular arrays and
hashes or array and hash references.  Do not name references with "ref"
or the data type in the name.

    @stories     = (1, 2, 3);      # right
    $comment_ref = [4, 5, 6];      # wrong
    $comments    = [4, 5, 6];      # right
    $comment     = $comments->[0]; # right

Make the name descriptive.  Don't use variables like "$sc" when you
could call it "$story_count".  See L<"Comments">.

Methods and Functions (except for special cases, like AUTOLOAD) begin
with a verb, with words following to complete the action. 
Multi-word names should be all lower-case, separated by underscores,
in keeping with the "perlstyle" guide and most of the modules
already on CPAN.  They
should as clearly as possible describe the activity to be peformed, and
the data to be returned.

    $obj->getStory();             # wrong.
    $obj->setStoryByName();       # wrong again.
    $obj->getStoryByID();         # wrong again. This isn't Java!

    $obj->get_story();            # right.
    $obj->set_story_by_name();    # right.
    $obj->get_story_by_id();      # right.

Methods and Functions beginning with C<_> are special:
they are not to be used
outside the current file (i.e. "private"). 
This is not enforced by the code itself,
but by programmer convention only.

For large for() loops, do not use $_, but name the variable.
Do not use $_ (or assume it) except for when it is absolutely
clear what is going on, or when it is required (such as with
map() and grep()).

    for (@list) {
        print;              # OK; everyone knows this one
        print uc;           # wrong; few people know this
        print uc $_;        # better
    }

Note that the special variable C<_> I<should> be used when possible.
It is a placeholder that can be passed to stat() and the file test
operators, that saves perl a trip to re-stat the file.  In the
example below, using C<$file> over for each file test, instead of
C<_> for subsequent uses, is a performance hit.  You should be
careful that the last-tested file is what you think it is, though.

    if (-d $file) {         # $file is a directory
        # ...
    } elsif (-l _) {        # $file is a symlink
        # ...
    }

Package names begin with a capital letter in each word, followed by
lower case letters.

    App::Standard          # good
    App::Authz             # good
    App::MainCode          # good

Use all lower case for POD files which are documentation only.

    App::styleguide        # good for doc only

Naming for modules should be according to the following general rules.

    All App services which have *broad* support from the 
        p5ee@perl.org list would go into the "App" package
    Naming style is similar to other modules on CPAN
    Naming choice draws from precedent of other modules on CPAN
    Naming choice draws from precedent of J2EE

Packages which aren't intended to be instantiated as objects may
have an "adjective" or "concept" for a name
(i.e. App::Standard).  Packages which are
Modules/Classes and are intended to be instantiated as objects
should be nouns, potentially accompanied by modifying adjectives
(i.e. App::Authen::Principal).

=head2 Indents

Code checked into CVS must never contain tabs.
Patches of code with tabs do not email well, and different people
have their tabstops set different ways.
If you want to set tab stops on your editor, just make sure it
converts tabs to spaces when it saves the file.

Indentation for normal block-style coding should be 4 spaces. 
The settings for Emacs and vim are as follows.

=over

=item * x?emacs: cperl-mode

  .xemacs/custom.el:
  ------------------
  (custom-set-variables
     '(cperl-indent-level 4)
     '(cperl-continued-statement-offset 4)
     '(cperl-tab-always-indent t)
     '(indent-tabs-mode nil)
  )