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