NAME

CPANPLUS::Styleguide - Style guide for CPANPLUS contributions

DESCRIPTION

This is a list of guidelines for code to be integrated in the CPANPLUS namespace.

GUIDELINES

It is highly recommended that CPANPLUS submissions follow these guidelines. Code which does not should deviate for a good reason. For example, a Tk shell wouldn't be expected to follow the no non-core modules rule, because using that shell is not a requirement for using CPANPLUS. Apply common sense, and, if in doubt, send a mail to the development list at cpanplus-devel@lists.sourceforge.net.

The CPANPLUS Way

All code should run under warnings and strict, although strict refs may be disabled for sections if required.
Do not use global variables. Try to solve problems by storing values in objects, or, preferably, use closures to access private data.
The return values of function calls should be checked. This applies to functions like open, printing to filehandles and so on.
In general, avoid using eval or system calls. However, eval should be used to wrap modules which can die.
CPANPLUS should not die, croak or confess. With the exception of those in Shell modules, functions should not print either, but use Error to pass messages to the stack.
Follow the established division of functions in the project. Internals contains the grunt work. Backend provides a coding interface. Shell contains look and feel code. Errors and warnings are handled by Error. Configuration will always be read by Configure.
Do not hardcode locations, script names and so on. Always use Configure for this.
Code reuse is recommended. Reuse existing functions where possible. If needed, refactor them, but ensure backwards compatibility!
The API provided by Backend should be backwards compatible with earlier releases.
Try the perl solution first. Use command-line tools as a last resort.
Do not rely on modules which are not part of the core as of 5.5.3 with the exception of those bundled with CPANPLUS. If you must use modules which are not core, provide a less featured alternative function as well. CPANPLUS basic operation should not require the installation of any modules.
All solutions must be designed to work on all supported platforms.
All solutions must work for the target perl versions, which are 5.5.3 up to and including the latest bleadperl.
Functions should, in most cases, return a hash reference. Look at related functions to see what is appropriate.
Functions should take a hash of arguments, even if they currently only have one argument.
Follow any additional guidelines set forth in the perlstyle manpage and perlmodstyle

Code Appearance

Use four spaces (and not a literal tab) for indentation.
Module names should begin with a capital. Function names and variable names should begin with a lower case character. Mark private functions with a leading underscore (_).
Use comments as needed to explain code. Be elaborate and explain why you did or didn't use a particular solution when other possibilities suggest themselves. Use three hashes (###) to mark comments for the developers and a single hash (#) to comment out test code or other non-essential parts.

Submissions

Any new module added to the CPANPLUS name space should have an appropriate name. Check with the developers to see if the name you have in mind is suitable.
Accompany code with tests where appropriate.
Patches should be provided in diff format and be accompanied by text explaining the purpose of the code. Any changes which will necessitate changes in the POD documentation should not include the POD changes in the patch. Instead, these should be explicitly described in the mail.

AUTHORS

This pod text by Ann Barcomb <kudra@cpan.org>.

COPYRIGHT

This library is free software; you may redistribute and/or modify it under the same terms as Perl itself.