How do you PEP 8-name a class whose name is an acronym?
Question:
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.
Answers:
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.
#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
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.
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.
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#.
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.
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).
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:
-
When applying the rule would make the code less readable, even for someone who is used to reading code that follows the rules.
-
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).
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.
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.
#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
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.
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.
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#.
PEP-8 does cover this (at least partially):
Note: When using abbreviations in CapWords, capitalize all the letters of the abbreviation. Thus
HTTPServerErroris better thanHttpServerError.
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.
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).
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:
When applying the rule would make the code less readable, even for someone who is used to reading code that follows the rules.
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).