pep-8 vs. external interfaces?

R

Roy Smith

I'm building a Python language wrapper to an network protocol which
traditionally uses camelCase function names. I'm trying to make the
new code pep-8 compliant, which means function names should be written
this_way() instead of thisWay(). I've got a couple of choices open to
me.

I could convert all the protocol names to pep-8 style mechanically.
This is not as much work as it seems; the lowest-level Python code is
already machine generated from a tabular description of the protocol.
It's about one more line of code to convert getLibraries() to
get_libraries(). This will leave the result the cleanest from the
Python point of view. It'll also make the Python binding look a
little different from the C++, Java, Perl, etc, bindings.

Or, I could draw a line in the sand and say, "If it's a protocol
primitive, it stays as written. Otherwise, it's pep-8". That's a
little uglier because it's not always obvious to the user exactly
which names are protocol primitives and which are higher-level
operations.

I figure either way, somebody's going to complain that I did it
wrong :)

I realize there's no single correct answer here. I'm seeking input
from people who have faced this question before. Which way did you
go? In retrospect, was it the right decision?
 
C

Carl Banks

Or, I could draw a line in the sand and say, "If it's a protocol
primitive, it stays as written.  Otherwise, it's pep-8".  That's a
little uglier because it's not always obvious to the user exactly
which names are protocol primitives and which are higher-level
operations.

So the question becomes, "Why are you mixing protocol primitives and
high-level operations in the same namespace?" Because that's not
normally a well-advised thing to do.

1. If you answered, "I shouldn't be", you should separate them and use
camel case for the protocol primitives.

2. If you answered, "I'm including protocol primitive functions
alongside high-level operations because conceptually they are the
same, it's just that some functions happen to map directly to the
underlying protocol", you should follow PEP-8, because by doing that
you've implicity raised the protocol primitive functions to high-level
status.

3. If you answered, "Protocol primitives are in the same namespace for
convenience, but high-level users shouldn't use them", then you should
use camel case for the protocol primitives but prepend an underscore.

4. If you answered, "I include those functions in the same namespace
because I am following the example of other language bindings in Perl,
Java, Ruby, etc.,", then figure out whether it's important to be
consistent with Perl, Java, Ruby, etc., and if so, do whatever they
did. If not, see #1.


Carl Banks
 
P

Philip Semanchuk

I'm building a Python language wrapper to an network protocol which
traditionally uses camelCase function names. I'm trying to make the
new code pep-8 compliant, which means function names should be written
this_way() instead of thisWay(). I've got a couple of choices open to
me.

I could convert all the protocol names to pep-8 style mechanically.
This is not as much work as it seems; the lowest-level Python code is
already machine generated from a tabular description of the protocol.
It's about one more line of code to convert getLibraries() to
get_libraries(). This will leave the result the cleanest from the
Python point of view. It'll also make the Python binding look a
little different from the C++, Java, Perl, etc, bindings.

+1 for PEP 8 compliance. Programmers unfamiliar with the existing
protocol will appreciate its Pythonic feel instead of wondering why
the names are all "wrong". Those familiar with the existing protocol
will have to make a mental adjustment, but at least they'll be
adjusting to a target (standard Python style) that they presumably know.
I figure either way, somebody's going to complain that I did it
wrong :)

I promise to be the first to complain no matter what you choose. ;)


Good luck
Philip
 
A

Aahz

So the question becomes, "Why are you mixing protocol primitives and
high-level operations in the same namespace?" Because that's not
normally a well-advised thing to do.

1. If you answered, "I shouldn't be", you should separate them and use
camel case for the protocol primitives.

2. If you answered, "I'm including protocol primitive functions
alongside high-level operations because conceptually they are the
same, it's just that some functions happen to map directly to the
underlying protocol", you should follow PEP-8, because by doing that
you've implicity raised the protocol primitive functions to high-level
status.

3. If you answered, "Protocol primitives are in the same namespace for
convenience, but high-level users shouldn't use them", then you should
use camel case for the protocol primitives but prepend an underscore.

4. If you answered, "I include those functions in the same namespace
because I am following the example of other language bindings in Perl,
Java, Ruby, etc.,", then figure out whether it's important to be
consistent with Perl, Java, Ruby, etc., and if so, do whatever they
did. If not, see #1.

This deserves to be recorded on a web page somewhere -- can you stick it
on the wiki? (I got laid off two weeks ago, so if you're too busy,
would you like me to do it?)
--
Aahz ([email protected]) <*> http://www.pythoncraft.com/

"Debugging is twice as hard as writing the code in the first place.
Therefore, if you write the code as cleverly as possible, you are, by
definition, not smart enough to debug it." --Brian W. Kernighan
 

Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments. After that, you can post your question and our members will help you out.

Ask a Question

Members online

No members online now.

Forum statistics

Threads
473,744
Messages
2,569,484
Members
44,903
Latest member
orderPeak8CBDGummies

Latest Threads

Top