1HACKING
2=======
3
4Development of SOAP::Lite takes place on GitHub.
5
6git@github.com:redhotpenguin/soaplite.git
7
8Come on by and fork it and submit a pull request.
9
10Looking for a few good maintainers! We want you!
11
12SOAP::Lite CODING GUIDELINES
13============================
14
15SOAP::Lite's coding style in principle follows Perl Best Practices by
16Damian Conway, but allows deviances for speed and backward compatibility
17reasons.
18
19The following guidelines apply:
20
21- Symbol table operations
22   * SOAP::Lite heavily relies on symbol table operations. While this is
23   nothing bad, you should always try other variants like subclassing before.
24   Use symbol table operations as a last resort, and preferably consolidate
25   similar operations into utility functions.
26
27- Autoloading
28   * SOAP::Lite heavily relies on AUTOLOAD, often together with symbol table
29   operations. While this is nothing generally bad, it can lead to subtle
30   errors, for example when switching the underlying protocol handler of
31   a transport backend. Methods already autoloaded (and cached via symbol
32   table) remain, even if there's a equally named method in the new protocol
33   handler.
34   It's generally best not to rely on AUTOLOAD and symbol table operations -
35   subclassing is often more appropriate.
36
37- testing
38    * SOAP::Lite has a test coverage of >60%, but aims at 100%. Please write
39    a test first.
40    * Use author tests for testing guidelines. Disable author tests for
41    users - it's time consuming and of no use to have users run author tests.
42    Author tests are enabled by setting the "TEST_AUTHOR" environment
43    variable to a true value.
44
45- Indentation and formatting
46    * indent with spaces.
47    * indent 4 characters per level
48    * use \n (LF) for newlines, not CRLF
49    * use blank lines to separate paragraphs
50    * Coding style is similar to K&R (opening brace on last line, closing
51    brace on new line. No cuddled else)
52    * No trailing spaces allowed (except to indicate a blank line in a POD
53    source block)
54
55- Flow control
56    * postfix if is allowed for single statements only. Preferably for flow
57    control only like in:
58       return $self if ref $self;
59    * postfix for, while, until are not allowed.
60    * unless is not allowed at all. Use if not.
61    * goto is only allowed for jumping into subs. Nothing else.
62    * redo, next, last etc. are preferred over goto.
63
64- Strictness
65    * always use strict. Switch off for the smallest block
66    possible, but switch off if there's a reason (don't let tools like
67    perlcritic fool you: no strict qw(refs); is often required.
68
69- Naming
70    * variable names are lower case with _ separating words, except when
71    a XML Schema, SOAP, or WSDL name is name-giving (don't force portType to
72    become port_type)
73    * hashes should be named FOO_of, lists FOO_from, references FOO_ref.
74    * package names are CamelCase, except when a XML, SOAP or WSDL name is
75    name-giving (don't force 'int' to become 'Int'. However, simpleType
76    becomes SimpleType).
77    Protocol names for transport modules are all UPPERCASE, like in
78    SOAP::Transport::HTTP or in SOAP::Transport::MAILTO.
79
80- Subroutines
81    * Subroutines shouldn't be more than around 50 lines long
82    * @_ should be unpacked. Deviances are allowed for speed reasons. If
83    you're not unpacking @_ in a sub of say, 5 lines or more, please comment
84    what you're doing.
85    * The preferred idiom for unpacking @_ is:
86       my ($self, @arg_from) = @_;
87    or
88       my ($self, %arg_of) = @_;
89    $_[0] is preferred over shift, except where the rest of the parameter
90    stack is used en block later.
91    * Always return.
92
93- POD and comments
94    * Comments denoting some people's copyright on some piece of the code
95    MUST be kept intact.
96    * Comment extensively. Comments are the maintainer (and core developer's)
97    documentation - aid them where possible (your're probably doing yourself
98    a favor by adding extensive comments).
99    * Comment either in blocks or as hanging side comments (especially when
100    commenting @_ access).
101    Example:
102
103    sub baz {
104        # @_ not unpacked for speed reasons. Read:
105        # my ($self, $something, %args_of) = @_;
106
107        $_[0]->bar($_[1]);      # read as $self->bar($something);
108        $_[0]->foo($_[2..$#]);  # read as $self->foo(%args_of);
109        return;
110    }
111    * POD is located at end of file, preferably after __END__
112    * Complete POD coverage is essential. However, if the package in question
113    is used internally only, it's better to omit the POD completely - too many
114    PODs to look at confuse the average CPAN user.
115