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