import SOAP-WSDL 2.00_29 from CPAN
git-cpan-module: SOAP-WSDL git-cpan-version: 2.00_29 git-cpan-authorid: MKUTTER git-cpan-file: authors/id/M/MK/MKUTTER/SOAP-WSDL-2.00_29.tar.gz
This commit is contained in:
Martin Kutter
committed by
Michael G. Schwern
Michael G. Schwern
parent
2bad767211
commit
874251225f
@@ -1,7 +1,10 @@
|
||||
HACKING
|
||||
=======
|
||||
|
||||
Development of SOAP::WSDL takes place on sourceforge.net.
|
||||
|
||||
There's a svn repository available at
|
||||
https://svn.sourceforge.net/svnroot/soap-wsdl
|
||||
https://soap-wsdl.svn.sourceforge.net/svnroot/soap-wsdl
|
||||
|
||||
Engagement in the further development of this module is highly encouraged -
|
||||
many people have already contributed, and many more probably will.
|
||||
@@ -11,14 +14,118 @@ so if you feel your changes are urgent, please set up a sourceforge account
|
||||
and ask me for commit permissions on the repository - I will happily accept
|
||||
you as co-author.
|
||||
|
||||
The (my) current roadmap for SOAP::WSDL is:
|
||||
TODO shows the current roadmap.
|
||||
|
||||
1.2*: Bugfixes and support for more XSD variants
|
||||
SOAP-WSDL CODING GUIDELINES
|
||||
===========================
|
||||
|
||||
1.3: Bindings support
|
||||
DESIGN PRINCIPLES
|
||||
-----------------
|
||||
|
||||
2.*: WSDL -> Perl Class factory with offline WSDL processing
|
||||
SOAP-WSDL is designed for the following principles:
|
||||
|
||||
May 2007,
|
||||
1. SPEED
|
||||
A SOAP toolkit is useless, if it's not fast enough. Therefore SOAP::WSDL aims
|
||||
at always being fast enough.
|
||||
|
||||
Please benchmark any contributions - if they slow down SOAP-WSDL (especially
|
||||
the XML parsing part), you should have good reasons.
|
||||
|
||||
2. USABILITY
|
||||
SOAP-WSDL is designed user-friendly. It tells the user whether it's
|
||||
capable of handling some WSDL or not, it gives friendly error messages, and
|
||||
if a user happens to call a non-existant method on XSD objects, they croak
|
||||
with a list of available methods to ease development.
|
||||
|
||||
3. EXTENSIBILITY
|
||||
If you plan an extension, look if the extension itself should be extensible,
|
||||
and which extension points to use.
|
||||
|
||||
Creating new extension points is highly appreciated.
|
||||
|
||||
4. MAINTAINABILITY
|
||||
SOAP::Lite unfortunately shows where a toolkit can go without focus on
|
||||
maintainability. SOAP::WSDL tries to be highly maintainable and easy to
|
||||
understand.
|
||||
|
||||
CODING STYLE
|
||||
------------
|
||||
|
||||
The principles above dictate a clear, but not too lengthy coding style.
|
||||
|
||||
SOAP::WSDL's coding style in principle follows Perl Best Practices by
|
||||
Damian Conway, but allows deviances for speed reasons
|
||||
|
||||
The following guidelines apply:
|
||||
|
||||
- Testing
|
||||
* SOAP::WSDL has a test coverage of >95% and 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.
|
||||
|
||||
- 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.
|
||||
* 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 and Warnings
|
||||
* always use strict and warnings. Switch off for the smallest block
|
||||
possible, but switch of 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).
|
||||
|
||||
- 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.
|
||||
* Always return. Always return. A single "return" allows perl to execute
|
||||
the subroutine in question in void context, which saves it from putting
|
||||
it's result in a temporary variable. Always return.
|
||||
|
||||
- POD and comments
|
||||
* 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.
|
||||
|
||||
July - November 2007,
|
||||
|
||||
Martin Kutter
|
||||
Reference in New Issue
Block a user