view release on metacpan or  search on metacpan

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

#############################################################################
## $Id: perlstyle.pod,v 1.2 2002/11/01 20:18:22 spadkins Exp $
#############################################################################

=head1 NAME

App::perlstyle - App::Context Perl Style Guide

=head1 INTRODUCTION

The following document describes some of the coding standards used in
writing the App::Context framework (App-Options, App-Context, App-Repository,
App-Widget, and other minor distributions).  This document exists for two
purposes:

=over

=item 1. To provide a guideline for people who wish to contribute to or
extend code in the App::Context framework.

=item 2. To provide a samples style guide to any development group who
desires a simple, effective coding standard for programming in Perl.

=back

Note that these are all guidelines, not unbreakable rules. 

Note that with much of this document, it is not so much the Right Way as
it is One Reasonable Way.  Everyone needs to have conventions in order to
make life easier.

=head1 CODING PRINCIPLES

=head2 Perl Version

The gold standard for backward compatibility is to support back to Perl
5.5.3 (5.005_03).  When writing code, try to write it so that it will
run on Perl 5.5.3.

=head2 Documentation

All modules will be documented using the POD examples in the module
boilerplate.  The function, purpose, use of the module will be
explained, and each public API will be documented with name,
description, inputs, outputs, side effects, etc.

If an array or hash reference is returned, document the size of the
array (including what each element is, as appropriate) and name each key
in the hash.  For complex data structures, map out the structure as
appropriate.

Also document what kind of data returned values are.  Is it an integer,
a block of HTML, a boolean?

All command-line program options will be documented using the
boilerplate code for command-line programs.  Each available function,
switch, etc. should be documented, along with a statement of function,
purpose, use of the program.  Try not to use the same options as another
program, for a different purpose.

All web programs should be documented with a statement of function,
purpose, and use in the comments of the program.

Any external documents, and documentation for command-line programs and
modules, should be written in POD, where appropriate. From there, they
can be translated to many formats with the various pod2* translators. 
Read the perlpod manpage before writing any POD, because although POD is
not difficult, it is not what most people are used to.  It is not a
regular markup language; it is just a way to make easy documentation
for translating to other formats.  Read, and understand, the perlpod
manpage, and ask us or someone else who knows if you have any questions.

=head2 Version

Use the boilerplate code for versions of modules, web programs, and
command-line programs.  The $VERSION of the module will then reflect the
CVS revision. 
The Makefile.PL should contain the distribution version, independent
of any individual file version within the CVS repository.

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

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

    Revision 1.2  2001/11/30 16:00:52  spadkins
    Renamed 'Component' to 'Service' throughout. Improved perldocs.

    Revision 1.1  2001/11/22 05:16:59  spadkins
    Major new architectural framework proposal

    Revision 1.1  2001/11/16 23:21:38  spadkins
    initial stuff



=head1 VERSION

$Id: perlstyle.pod,v 1.2 2002/11/01 20:18:22 spadkins Exp $