view release on metacpan or  search on metacpan

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

    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)
  )

=item * vim

  .vimrc:
  -------
  set expandtab " replaces any tab keypress with the appropriate number of spaces
  set tabstop=4 " sets tabs to 4 spaces

=back

=head2 Line Lengths

Maximum line lengths should be 77 columns (or 75 columns for
an unbroken line of characters).
This is for maximum portability to different people's
development environments and for decent transmission
through e-mail to a wide array of e-mail clients
(i.e. for patches).

Example: Eudora 3.0.6 wraps a solid, single line of 80 non-whitespace
characters (i.e. ######...#####) at character 76.  If there are
spaces in the line, it allows lines up to character 78 before wrapping
the last words down to the next line.  If sources have no more than
77 characters in a line, a "diff -u" patch will add a column, and the
lines will escape being folded.

=head2 Blank Space

No space before a semicolon that closes a statement.

    foo(@bar) ;     # wrong
    foo(@bar);      # right

Line up corresponding items vertically.

    my $foo   = 1;
    my $bar   = 2;
    my $xyzzy = 3;

    open(FILE, $fh)   or die $!;
    open(FILE2, $fh2) or die $!;

    $rot13 =~ tr[abcedfghijklmnopqrstuvwxyz]
                [nopqrstuvwxyzabcdefghijklm];

    # note we use a-mn-z instead of a-z,
    # for readability
    $rot13 =~ tr[a-mn-z]
                [n-za-m];

Put blank lines where they make sense for readability, such as
the following.
Put blank lines between groups of code that do different things.  Put
blank lines after your variable declarations.  Put a blank line before a
final return() statement.  Put a blank line following a block (and
before, with the exception of comment lines).

An example:

    # this is my function!
    sub foo {
        my (@data) = @_;
        my $obj = new Constructor;
        my ($var1, $var2);

        $obj->setFoo($data[1]);
        $var1 = $obj->getFoo(1);
        $var2 = $obj->getFoo($var1);

        display($var1, $var2);

        return($data[0]);
    }

    print 1;


=head2 Parentheses

For control structures, there is a space between the keyword and opening
parenthesis.  For functions, there is not.

    for(@list)         # wrong
    for (@list)        # right

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

    baz($buz) if foo($bar);

Most of the time, the confusion between and/&&, or/|| can be alleviated
by using parentheses.  If you want to leave off the parentheses then you
I<must> use the proper operator.  But if you use parentheses -- and
normally, you should, if there is any question at all -- then it doesn't
matter which you use.  Use whichever is most readable and aesthetically
pleasing to you at the time, and be consistent within your block of code.

Break long lines AFTER operators, except for "and", "or", "&&", "||".
Try to keep the two parts to a binary operator (an operator that
has two operands) together when possible.

    print "foo" . "bar" . "baz"
        . "buz";                    # wrong

    print "foo" . "bar" . "baz" .
        "buz";                      # right

    print $foo unless $x == 3 && $y ==
        4 && $z == 5;               # wrong

    print $foo unless $x == 3 && $y == 4
        && $z == 5;                 # right


=head2 Other

Put space around a complex subscript inside the brackets or braces.

    $foo{$bar{baz}{buz}};       # OK
    $foo{ $bar{baz}{buz} };     # better

In general, use single-quotes around literals, and double-quotes
when the text needs to be interpolated. 

It is OK to omit quotes around names in braces and when using
the => operator, but be careful not to use a name that doubles as
a function; in that case, quote.

    $what{'time'}{it}{is} = time();

When making compound statements, put the primary action first.

    open(FILE, $fh) or die $!;      # right
    die $! unless open(FILE, $fh);  # wrong

    print "Starting\n" if $verbose; # right
    $verbose && print "Starting\n"; # wrong


Use here-docs instead of repeated print statements.

        print <<EOT;
    This is a whole bunch of text.
    I like it.  I don't need to worry about messing
    with lots of print statements and lining them up.
    EOT

Just remember that unless you put single quotes around your here-doc
token (<<'EOT'), the text will be interpolated, so escape any "$" or "@"
as needed.



=head1 REQUIREMENTS RFC AND CODING PROCEDURE

This is for new programs, modules, specific APIs, or anything else.

Contact for core team is the App-development mailing list.
Discuss all ideas there.

The basic process for a new App service is:

    get the blessing from the App list for a top-level package name
    (i.e. "App::NewModule")
    begin a CPAN-able source directory skeleton
    write the spec (no code) as POD inside the target module(s)
    publish HTML to the web
    announce whenever progress is made so that comments can be sought
    code is added after there is broad support for the API spec
    and supporting doc


=head1 BUG REPORTS, PATCHES, CVS

We don't have bug tracking set up yet.

Use C<diff -u> for patches.

Do not add anything to the main branches in CVS without approval from
a member of the core team.


=head1 TO DO

lots

=head1 ACKNOWLEDGEMENTS

This style guide was based on the slashcode style guide.
It is in conformance with the general Perl style guide
(perldoc perlstyle) and the mod_perl style guide.

  http://slashcode.com/docs/slashstyle.html
  http://search.cpan.org/author/JHI/perl/pod/perlstyle.pod
  http://perl.apache.org/docs/2.0/devel/modperl_style/modperl_style.html

It is also in the spirit of the C-language Apache style guide.

  http://httpd.apache.org/dev/styleguide.html


=head1 CHANGES

    $Log: perlstyle.pod,v $
    Revision 1.2  2002/11/01 20:18:22  spadkins
    convert from P5EEx::Blue to App::Context

    Revision 1.1  2002/09/09 01:34:10  spadkins
    first import