Opinions: API wrapping, how close to original API should you stay?

[Peter Edwards]

I usually prefer get_optimistic_lock() as a style of function naming and
that's what I use for perl, though I use the getOptimisticLock style if I'm
writing VB/VC++ as it's easier for other developers to maintain.

In this case the semantic meaning is "get" and the following part looks like
an argument to an XPath search pattern so maybe it would be worth
considering the calling interface in
http://search.cpan.org/~samtregar/Class-XPath-1.4/XPath.pm

Or you could use XML::Simple to map to a perl structure and auto-generate
some accessor methods from a list of keywords if the XML structure is simple
enough.

Regards, Peter

-----Original Message-----
From: miltonkeynes-pm-bounces+peter=dragonstaff.com at pm.org
[mailto:miltonkeynes-pm-bounces+peter=dragonstaff.com at pm.org] On Behalf Of
Nik Clayton
Sent: 04 October 2006 20:41
To: London.pm Perl M[ou]ngers; Milton Keynes Perl Mongers
Subject: Opinions: API wrapping, how close to original API should you stay?

Hi all,

I'm seeking opinions.  I'm in the middle of writing some code that wraps 
someone else's SOAP API.

The SOAP API returns XML that looks a bit like this:

   ...
   <OptimisticLock>...</OptimisticLock>
   <Id>...</Id>
   <ParentId>...</ParentId>
   <FullName>...</FullName>
   ...

Basically, CamelCase all over the shop.

I'm turning that in to an object, with accessors for the various 
elements[1].  One accessor per XML element.

Assuming you were writing to this API, would you prefer to use:

    $ml->get_optimistic_lock()

    $ml->get_OptimisticLock()

    $ml->getOptimisticLock()

to retrieve the value, or something else?

At the moment, I'm leaning towards the first.  It's simple and regular, 
but it does mean that the programmer has to translate in their head from 
the original API documentation.

The second lessens that translation slightly, but then the symbol 
inconsistently uses CamelCase and '_' to separate components.

That last one, to my eyes, just looks ugly.

N

[1] No, not just a hash ref -- debugging "$foo->get_optimistc_lock()" is 
much nicer than debugging "$foo->{optimistc_lock}".
_______________________________________________
MiltonKeynes-pm mailing list
MiltonKeynes-pm at pm.org
http://mail.pm.org/mailman/listinfo/miltonkeynes-pm