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