[Catalyst] Why does $c->stats require -Debug flag?

[Jon Schutz]

On Fri, 2008-04-25 at 15:53 +0100, Matt S Trout wrote:
> 
> There's no written standard currently; I'd love to see somebody take a
> crack at writing one but I'm not sure what would need to go in it.
> 

I've attached a draft based on some of our company procedures to show
the sorts of things that need to be addressed.  I've changed a few
things to reflect some of the Catalyst conventions that I am aware of
but it will need your input, particular w.r.t. any conventions from PBP
that you disagree with.

> > having this interesting discussion.  Can we put a timescale on it?  What
> > is the plan for release of 5.7013 and/or 5.80?
> 
> Next week or two would be ideal; if you can't make time that soon then
> you need to say -now- so somebody else can fix this.
> 

I'd need 2-3 weeks as the next week and a half is out and I'm concerned
about the time it will take to review the original code to check the
subtleties, and then write new tests.  The code itself is only a few
minutes work...

-- 

Jon Schutz                        My tech notes http://notes.jschutz.net
Chief Technology Officer                        http://www.youramigo.com
YourAmigo         
-------------- next part --------------
(Proposed) Catalyst Coding Standards and Policies

This document outlines the standards and policies for contributing to the
Catalyst Project and attempts to capture the conventions that the project team
has chosen to use to ensure that the quality and consistency of the code base is
maintained.  The project greatly benefits from the many contributors in the
Catalyst community, and in turn the wider Catalyst community benefits from
consistent and reliable code through adherence to these agreed standards.

Any questions or clarifications regarding this document should be directed to
the Catalyst mailing list.

These standards are to be applied for core Catalyst development and are
recommended for use with plugins and other contributed code.

1. Coding Standards

1.1.  "Perl Best Practices" (Oreilly, Conway) should be followed unless
    otherwise noted here.

1.2. All code shall be clear of perlcritic warnings (at severity level 5), with
     the following exemptions:

         1. Stricture disabled at line ... See page 429 of PBP. (Severity: 5)

            This warning is acceptable providing the 'no strict ...' is applied
            within the minimum scope necessary. (perlcritic does not seem to be
            able to reliably recognise minimum scope).

1.3 Indentation

Use 4-space indentation.  Hard tabs are prohibited.

2. Documentation Standards

Please familiarise yourself with the Perl Best Practices description of types of
documentation.

2.1 All User API functions shall have appropriate documentation suitable for end
users of the API.  These should appear in perldoc.

2.2 Documentation associated with functions and methods that are not part of the
  User API shall be as follows:

  - private functions and methods (as identified by a leading underscore in
  the function/method name) shall have any documentation in comments so as
  to not appear in perldoc.

  - internal functions and methods (meant for use within the same package only)
  shall be flagged as such and have documentation in comments so as to not
  appear in perldoc.

  - internal functions and methods that are not for general users buy may be
  used by extensions (which may be packaged separately, such as derived classes
  or plugins) should appear in perldoc, clearly identified as "Developer API"
  methods.


3. Testing Guidelines

Write the documentation for your API functions to adequately define the inputs
and expected outputs.  Then write tests that match.

    * Each module should have at least one corresponding file in the 't/' test
    directory. Permissible exceptions:
          o where the module is trivial, such that it can be adequately tested by code inspection
          o where the module requires external infrastructure (e.g. a remote
    website) which is unreasonable to duplicate; in this case it may be more
    appropriate to add a working example into the 'examples/' subdirectory. Make
    sure that everything that can be reasonably tested through a regression
    test, is; this might mean splitting the module, placing the reusable,
    testable components in their own modules and keeping the application level
    code that requires the external infrastructure separate.

          o modules which only include configuration data for a suitably tested parent class  may not need their own tests 

    * All public methods (user and developer API methods) should be tested. Permissible exceptions:
          o where the method is inherited and suitably tested in the parent class
          o where the method is created through configuration of a suitably
    tested parent (such as accessors created using Class::Data::Inheritable or
    Class::Accessor) 

    * Testing of private/protected methods may be appropriate when sufficient
    test coverage is difficult to achieve when testing through the public
    methods.  Due to the possible maintenance issues that this might cause, it
    should be used sparingly.

    * Do a test coverage analysis using Devel::Cover. Target test coverage as reported by Devel::Cover should be >80% for each module. 

    Devel::Cover invocation:

    cover -delete
    HARNESS_PERL_SWITCHES=-MDevel::Cover make test
    cover

4. Contributing patches

4.1 Patches should be against the current CVS head revision.

4.2 Ensure your patches are accompanied by tests and appropriate documentation
  as described above. 

4.3 Submit your patch to the Catalyst mailing list for public review, and from
  where the maintainer responsible can take the patch and apply it.  Include a
  description of the problem, a failing test case (pre-patch), and a description
  of how your patch overcomes the problem.

4.4 When providing patches to any module, please review the module in the
  context of the standards and policies on this page, and upgrade if necessary.

5. Review and Release Guidelines

5.1 Backward Compatibility

5.2 Point Releases and Major Releases

5.3 Review Procedure

5.4 Release Procedure

5.5 Who's responsible


REFERENCES

Perl Best Practices, Damien Conway,
http://www.oreilly.com/catalog/perlbp/toc.html

Catalyst::Manual::DevelopmentProcess

Catalyst::Manual::ExtendingCatalyst