HACKING
=======
Development of SOAP::Lite takes place on GitHub.
git@github.com:redhotpenguin/perl-soaplite.git
Come on by and fork it and submit a pull request.
Looking for a few good maintainers! We want you!
SOAP::Lite CODING GUIDELINES
============================
SOAP::Lite's coding style in principle follows Perl Best Practices by
Damian Conway, but allows deviances for speed and backward compatibility
reasons.
The following guidelines apply:
- Symbol table operations
* SOAP::Lite heavily relies on symbol table operations. While this is
nothing bad, you should always try other variants like subclassing before.
Use symbol table operations as a last resort, and preferably consolidate
similar operations into utility functions.
- Autoloading
* SOAP::Lite heavily relies on AUTOLOAD, often together with symbol table
operations. While this is nothing generally bad, it can lead to subtle
errors, for example when switching the underlying protocol handler of
a transport backend. Methods already autoloaded (and cached via symbol
table) remain, even if there's a equally named method in the new protocol
handler.
It's generally best not to rely on AUTOLOAD and symbol table operations -
subclassing is often more appropriate.
- testing
* SOAP::Lite has a test coverage of >60%, but aims at 100%. Please write
a test first.
* Use author tests for testing guidelines. Disable author tests for
users - it's time consuming and of no use to have users run author tests.
Author tests are enabled by setting the "AUTHOR_TESTING" environment
variable to a true value, or when running "dzil test".
- Indentation and formatting
* indent with spaces.
* indent 4 characters per level
* use \n (LF) for newlines, not CRLF
* use blank lines to separate paragraphs
* Coding style is similar to K&R (opening brace on last line, closing
brace on new line. No cuddled else)
* No trailing spaces allowed (except to indicate a blank line in a POD
source block)
- Flow control
* postfix if is allowed for single statements only. Preferably for flow
control only like in:
return $self if ref $self;
* postfix for, while, until are not allowed.
* unless is not allowed at all. Use if not.
* goto is only allowed for jumping into subs. Nothing else.
* redo, next, last etc. are preferred over goto.
- Strictness
* always use strict. Switch off for the smallest block
possible, but switch off if there's a reason (don't let tools like
perlcritic fool you: no strict qw(refs); is often required.
- Naming
* variable names are lower case with _ separating words, except when
a XML Schema, SOAP, or WSDL name is name-giving (don't force portType to
become port_type)
* hashes should be named FOO_of, lists FOO_from, references FOO_ref.
* package names are CamelCase, except when a XML, SOAP or WSDL name is
name-giving (don't force 'int' to become 'Int'. However, simpleType
becomes SimpleType).
Protocol names for transport modules are all UPPERCASE, like in
SOAP::Transport::HTTP or in SOAP::Transport::MAILTO.
- Subroutines
* Subroutines shouldn't be more than around 50 lines long
* @_ should be unpacked. Deviances are allowed for speed reasons. If
you're not unpacking @_ in a sub of say, 5 lines or more, please comment
what you're doing.
* The preferred idiom for unpacking @_ is:
my ($self, @arg_from) = @_;
or
my ($self, %arg_of) = @_;
$_[0] is preferred over shift, except where the rest of the parameter
stack is used en block later.
* Always return.
- POD and comments
* Comments denoting some people's copyright on some piece of the code
MUST be kept intact.
* Comment extensively. Comments are the maintainer (and core developer's)
documentation - aid them where possible (your're probably doing yourself
a favor by adding extensive comments).
* Comment either in blocks or as hanging side comments (especially when
commenting @_ access).
Example:
sub baz {
# @_ not unpacked for speed reasons. Read:
# my ($self, $something, %args_of) = @_;
$_[0]->bar($_[1]); # read as $self->bar($something);
$_[0]->foo($_[2..$#]); # read as $self->foo(%args_of);
return;
}
* POD is located at end of file, preferably after __END__
* Complete POD coverage is essential. However, if the package in question
is used internally only, it's better to omit the POD completely - too many
PODs to look at confuse the average CPAN user.