views:

197

answers:

8

I try to adhere to the style guide for Python code (also known as PEP 8). Accordingly, the preferred way to name a class is using CamelCase:

Almost without exception, class names use the CapWords convention. Classes for internal use have a leading underscore in addition.

How can I be consistent with PEP 8 if my class name is formed by two acronyms (which in proper English should be capitalized). For instance, if my class name was 'NASA JPL', what would you name it?:

class NASAJPL():  # 1
class NASA_JPL(): # 2
class NasaJpl():  # 3

I am using #1, but it looks weird; #3 looks weird too, and #2 seems to violate PEP 8.

Thoughts?

EDIT:

Many thanks for your answers. While the question really does not have a 'correct' answer, I benefited a lot from your insights.

I will be resorting to a #3: better to be consistently wrong (in the sense of having an acronym/abbreviation as a Title) than inconsistently right.

Thanks again.

+2  A: 

It depends on the acronym. Another option would be class NASAJpl():, which makes it seem that "NASA" is the primary part, and "JPL" is the subordinate part.

Ignacio Vazquez-Abrams
+3  A: 

#1 in this particular case looks fine to me (if it's really an acronym). Out of curiosity, what does it stand for (and what exactly is the class instance, maybe a module would be the more appropriate divisor)?

class NASAJPL:

EDIT: when you're combining two acronyms chances are you want to divide functionality over modules (you never know when you're adding that next feature to your program):

from NASA import JPL
from NASA import ARC
ChristopheD
National Air and Space Administration Jet Propulsion Laboratory. Either that, or I'm being a proper geek and reading too much into things.
Dan
What, the National Aeronautical and Space Administration's Jet Propulsion Laboratory?
Ignacio Vazquez-Abrams
I used the acronyms NASA and JPL as an example (National Aeronautics and Space Administration / Jet Propulsion Laboratory). In my actual application I have other acronyms (many of them!)
Arrieta
@Dan: Based on the asker's gravatar and profile...
Ignacio Vazquez-Abrams
Edited answer based on the viability of seperating two acronyms into seperate namespaces using modules.
ChristopheD
The problem with #1 is that `NASAJPL`, `JPL` and `ARC` look like symbolic constants, for which all-caps is used both in PEP8 and in the wider world.
bobince
+6  A: 

I also work in an acronym-heavy environment. I tend to prefer form #3 because even though it lower-cases parts of an acronym, it clearly delineates parts of the name. It also avoids confusion when part of the name is an acronym and part is a word.

Adam
Agreed. Consistent capitalization I find tends to make things easier when reading code. You know when reading English that a capital means a name. Likewise, in Python (via PEP-8), when come across something CamelCased, you know it's a class.
Bryan Ross
+2  A: 

I tend to use #3. It looks weird at first but you (sort of) get used to it. I went this way after suffering for too long under strings of acronyms jammed together, e.g. NPCAIXMLParser was one. I decided that NpcAiXmlParser was much easier to read and have been doing that ever since, even though seeing these things lowercased still looks weird sometimes.

In terms of "the standards," I tend to think of these entities as "words" and as such capitalize them as I would capitalize any other word. E.g. if I had a local variable representing some NPC (non-player character), I would name it 'npc' and not 'nPC'.

In regards to PEP-8, I disagree with this statement; I find the last spelling of the word to be preferable.

Note: When using abbreviations in CapWords, capitalize all the letters of the abbreviation. Thus HTTPServerError is better than HttpServerError.

dash-tom-bang
Curious why the downvote, given similar content (but earlier posting) to other upvoted answers?
dash-tom-bang
+2  A: 

Number 1 is too hard to read for me - there's no way to tell that's it's two acronyms.

Number 2 violates PEP8, but looks fine. Remember "A foolish consistency is the hobgoblin of little minds" :)

I like number 3 the best, but I do a lot of C# programming - that's how you'd be supposed to do it in C#.

Dan
+13  A: 

PEP-8 does cover this (at least partially):

Note: When using abbreviations in CapWords, capitalize all the letters of the abbreviation. Thus HTTPServerError is better than HttpServerError.

Which I would read to mean that NASAJPL() is the recommended name according to PEP-8.

Personally I'd find NasaJpl() the easiest to scan since the upper case letters easily mark word boundaries and give the name a distinctive shape.

Dan Head
I agree. PEP-8 isn't Holy Law. Break any of its rules sooner than code anything outright barbarous. (In which category I would count `NASAJPL()`.)
bobince
I will be accepting your answer as the 'closest to consensus' Many thanks.
Arrieta
+2  A: 

As others have noted, NASAJPL is probably the PEP-8 approved form.

Just to be contrary, however, I would probably use NasaJPL. Because if you are reading it, you pronounce "NASA" as a single word, whereas "JPL" you spell out.

You can make an argument that this is consistent with PEP-8, since "NASA" is an acronym, but "JPL" is an abbreviation (or initialism, if you want to get pedantic).

Dan Menes
+2  A: 

You're Doing it Right.

If ChristophD's split it into a module hierarchy suggestion isn't a viable option, then I'd suggest your #2 form (class NASA_JPL ():) is the most legible, PEP-8 be damned.

No, really...

That said... I don't think PEP-8 need be damned in order for you to use that option and still adhere to its core principles. As you point out in your original question, itself, the first sentence of the "CamelCase class names" guideline begins:

Almost without exception, [...]

PEP-8's "fundamental principles" statement, as Dan alludes to with the "A Foolish Consistency [...]" line, declares legibility and comprehensibility the primary goals of PEP-8's recommendations. PEP-8 is a collection of established, successful patterns in service to those goals.

Emerson on the application of PEP-8 to reality...

Fundamentally, any system has aspects which are necessarily inconsistent with the character of the whole. When a system makes good and consistent use of a style guide's recommendations, any inconsistencies will be conscious responses to necessity. (I regard maintaining the legibility of corner cases as a necessity.)

When handled this way, those inconsistencies, counter-intuitively, reinforce the cohesion of the whole, rather than disrupting it.

PEP-8 states this more succinctly (and, thus, more usefully :) ):

But most importantly: know when to be inconsistent -- sometimes the style guide just doesn't apply. When in doubt, use your best judgment. Look at other examples and decide what looks best. And don't hesitate to ask!

Two good reasons to break a particular rule:

  1. When applying the rule would make the code less readable, even for someone who is used to reading code that follows the rules.

  2. To be consistent with surrounding code that also breaks it (maybe for historic reasons)—although this is also an opportunity to clean up someone else's mess (in true XP style).

Tripp Lilley