Naming Conventions (PEP 8)

A place where you can post Python-related tutorials you made yourself, or links to tutorials made by others.

Naming Conventions (PEP 8)

Postby micseydel » Fri Feb 22, 2013 1:10 am

NOTE: There's definitely wiggle room when it comes to these conventions. Some are more important than others, and you're welcome to read the discussion in the replies. Following these standards certainly won't hurt though ;)

Python allows any name with upper- and lowercase letters as well as underscores (_). However, there are conventions that the Python community follow in order to standardize things and make reading others' code more easy. We follow PEP 8 (this link links specific to the naming conventions section, and is not PEP 8-comprehensive) but I'll go in order that people learn things and so will be more useful here, rather than the other they use in PEP 8.

Typical variables
Typical variable names should be descriptive, and may use underscore_style for separating words when it increases readability (they're not always necessary, use your best judgment!). You wouldn't use the variable name x for a string which represents a user's name. You would use name, user_name, username or something of the sort. Capitalized is strongly discouraged, and mixedCase is not considered Pythonic, although mixedCase is less of a priority. CamelCase is confusing for regular variables since it is used for classes. Constants are often denoted by ALL_CAPS and underscores separate words. Capitalized_Words_With_Underscores is longer than necessary and terribly ugly.

If you are adding code to a project which uses a style other than what is described here, use that style instead. Consistency is why we do this, and consistency is what you should strive for.

Names to avoid
PEP 8 wrote:Never use the characters 'l' (lowercase letter el), 'O' (uppercase letter oh), or 'I' (uppercase letter eye) as single character variable names.

You should also avoid using built-in names, such as "sum". You are unable to use names such as "class" since it is a keyword, however the recommended alternative is to append an underscore like "class_". The extra underscore is preferred over something like "clss".

Functions
Follow typical variable naming conventions for functions. If a function returns the same thing always, don't make it an UPPERCASE_FUNCTION, just do the constant.

Classes
Classes use CamelCase, and should be singular. A "car" class should be Car, not Cars. A big number class would be BigNumber.

Class methods
Same as functions, although the first argument to a method should be "self" and for a static method it should be "cls".

Private class attributes/methods
You can prepend an underscore (_) to indicate that something is private, or use double underscore (__) to denote that something is very, very private. There is controversy over whether the double underscore should be used. (A user can still access a "private" attribute/method, however doing so is discouraged because it could be an implementation detail that can change, rather than being part of the interface for the object.)

Packages
Package names should be lowercase, even when they contain only a single class which should be CamelCase.

Exceptions
Exceptions, being classes, follow class conventions.

Regulars please give feedback on this! And other mods, feel free to make edits if you deem it with doing.
Join the #python-forum IRC channel on irc.freenode.net!
User avatar
micseydel
 
Posts: 939
Joined: Tue Feb 12, 2013 2:18 am
Location: Mountain View, CA

Re: Naming Conventions (PEP 8)

Postby ichabod801 » Fri Feb 22, 2013 1:44 am

I am uncomfortable with this, except for the "Typical Variables" section. I think this post emphasizes the wrong things about PEP 8. I have seen this emphasis in other posters before, but this is more like the board officially endorsing it. Note that some of the core packages don't even follow everything about PEP 8

The purpose of good coding style is to make your code understandable. What capitalization you use when and whether you use four spaces, eight spaces, or tabs for indentation is the least important part of it. You can use four space tabs and underscores for function names and still produce gibberish code.

The key points to my mind are using descriptive names (covered), being consistent in capitalization and indentation, commenting your code, and providing block comments for functions, classes, and modules.

IMHO
Craig "Ichabod" O'Brien
Minimalist, buddhist, theist, and programmer
Current languages: Python, SAS, and C++
Previous serious languages: R, Java, VBA, Lisp, HyperTalk, BASIC
ichabod801
 
Posts: 84
Joined: Sat Feb 09, 2013 12:54 pm
Location: Outside Washington DC

Re: Naming Conventions (PEP 8)

Postby micseydel » Fri Feb 22, 2013 1:51 am

Thanks ichabod, I edited to mention that consistency is the most important aspect here. Comments and doc strings are not variable names so they are not covered here, but you're welcome to create a "General Style" tutorial which augments that which is here.
Join the #python-forum IRC channel on irc.freenode.net!
User avatar
micseydel
 
Posts: 939
Joined: Tue Feb 12, 2013 2:18 am
Location: Mountain View, CA

Re: Naming Conventions (PEP 8)

Postby ichabod801 » Fri Feb 22, 2013 2:08 pm

That doesn't really address my concerns, but I guess I'm the lone dissenter on PEP 8 around here.
Craig "Ichabod" O'Brien
Minimalist, buddhist, theist, and programmer
Current languages: Python, SAS, and C++
Previous serious languages: R, Java, VBA, Lisp, HyperTalk, BASIC
ichabod801
 
Posts: 84
Joined: Sat Feb 09, 2013 12:54 pm
Location: Outside Washington DC

Re: Naming Conventions (PEP 8)

Postby micseydel » Fri Feb 22, 2013 6:41 pm

ichabod801 wrote:I am uncomfortable with this, except for the "Typical Variables" section. I think this post emphasizes the wrong things about PEP 8.


I have seen this emphasis in other posters before, but this is more like the board officially endorsing it.

Well, I personally would prefer a general endorsement of PEP 8. I wouldn't freak out if you used mixedCase variable names or anything, but I would discouraged CamelCase for non-classes.

Note that some of the core packages don't even follow everything about PEP 8

True, but this is seen as a mistake in Python 2, and has been mostly rectified in Python 3.

The purpose of good coding style is to make your code understandable. What capitalization you use when and whether you use four spaces, eight spaces, or tabs for indentation is the least important part of it. You can use four space tabs and underscores for function names and still produce gibberish code.

While descriptive variable names and semantic correctness is clearly very important, the Python community at large has considered PEP 8 worth creating and endorsing because

The key points to my mind are using descriptive names (covered), being consistent in capitalization and indentation, commenting your code, and providing block comments for functions, classes, and modules.

IMHO

ichabod801 wrote:That doesn't really address my concerns, but I guess I'm the lone dissenter on PEP 8 around here.

Could you be more specific about what more I need to address? I'd like our community to if not agree, then discuss everything, so maximize the quality of the forum.
Join the #python-forum IRC channel on irc.freenode.net!
User avatar
micseydel
 
Posts: 939
Joined: Tue Feb 12, 2013 2:18 am
Location: Mountain View, CA

Re: Naming Conventions (PEP 8)

Postby ichabod801 » Fri Feb 22, 2013 7:24 pm

micseydel wrote:I wouldn't freak out if you used mixedCase variable names or anything, but I would discouraged CamelCase for non-classes.


Why? If I am being otherwise consistent, what is wrong with that?

micseydel wrote:True, but this is seen as a mistake in Python 2, and has been mostly rectified in Python 3.


Not even close to mostly. If that was the case "PEP 8".startswith('P') would have been replaced by "PEP 8".starts_with('P'). Lack of underscores is all over the place, and unittest and threading still use mixedCase for methods. I'm sure I could find more examples if I looked closely.

micseydel wrote:While descriptive variable names and semantic correctness is clearly very important, the Python community at large has considered PEP 8 worth creating and endorsing because


The Python community at large did not create PEP 8. Guido von Rossum and Barry Warsaw created PEP 8. It was approved solely by Guido von Rossum. I know of no survey where the Python community at large endorsed PEP 8.

micseydel wrote:Could you be more specific about what more I need to address? I'd like our community to if not agree, then discuss everything, so maximize the quality of the forum.


You don't need to address anything. I'm willing to stand aside on this issue. That was meant to be the point of my last post, although looking back I admit that the point was totally not clear. :oops:

In any case, I think I've made my point and any newbies who come along can read it and decided for themselves.
Craig "Ichabod" O'Brien
Minimalist, buddhist, theist, and programmer
Current languages: Python, SAS, and C++
Previous serious languages: R, Java, VBA, Lisp, HyperTalk, BASIC
ichabod801
 
Posts: 84
Joined: Sat Feb 09, 2013 12:54 pm
Location: Outside Washington DC

Re: Naming Conventions (PEP 8)

Postby micseydel » Fri Feb 22, 2013 7:47 pm

ichabod801 wrote:
micseydel wrote:I wouldn't freak out if you used mixedCase variable names or anything, but I would discouraged CamelCase for non-classes.

Why? If I am being otherwise consistent, what is wrong with that?

Consistency within an individual is important, but I believe their is value to consistency among everyone. It just makes reading things faster.

micseydel wrote:True, but this is seen as a mistake in Python 2, and has been mostly rectified in Python 3.

Not even close to mostly. If that was the case "PEP 8".startswith('P') would have been replaced by "PEP 8".starts_with('P'). Lack of underscores is all over the place, and unittest and threading still use mixedCase for methods. I'm sure I could find more examples if I looked closely.

PEP reads exactly, "Underscores can be used in the module name if it improves readability." It does not require them, so str.startswith() is fine. It's like you're right about unittest, although it looks like threading actually did change things, but left some legacy references in (so "current_thread" and "currentThread" both exist in the module). But again, I'm less concerned about mixedCase and more concerned about everything else (most important, not using CamelCase since when I read the code, I think it's a class.

micseydel wrote:While descriptive variable names and semantic correctness is clearly very important, the Python community at large has considered PEP 8 worth creating and endorsing because


The Python community at large did not create PEP 8. Guido von Rossum and Barry Warsaw created PEP 8. It was approved solely by Guido von Rossum. I know of no survey where the Python community at large endorsed PEP 8.

It looks like I was mistaken and that you are right. However, just about every group that codes together creates a standard to follow, and I'd prefer that the forum generally make use of PEP 8 unless there's something we things ought to be different. Differences that come to my mind are that I don't really care about mixedCase, it doesn't bother me at all, and PEP 8 says to use triple quotes for doc strings but if I have a short doc string, I never use triple quotes.

micseydel wrote:Could you be more specific about what more I need to address? I'd like our community to if not agree, then discuss everything, so maximize the quality of the forum.


You don't need to address anything. I'm willing to stand aside on this issue. That was meant to be the point of my last post, although looking back I admit that the point was totally not clear. :oops:

In any case, I think I've made my point and any newbies who come along can read it and decided for themselves.

I think you've been helpfully more specific in your reply, and I appreciate it, and I like your point about others reading our discussion and deciding for themselves.
Join the #python-forum IRC channel on irc.freenode.net!
User avatar
micseydel
 
Posts: 939
Joined: Tue Feb 12, 2013 2:18 am
Location: Mountain View, CA

Re: Naming Conventions (PEP 8)

Postby ichabod801 » Fri Feb 22, 2013 8:56 pm

micseydel wrote:PEP reads exactly, "Underscores can be used in the module name if it improves readability." It does not require them, so str.startswith() is fine.


Actually, under function names it says "Function names should be lowercase, with words separated by underscores as necessary to improve readability." The same is stated for method names. Is it necessary to improve readability to use starts_with? Eh. I say, use underscores or don't, lest you write starts_with when you should have written startswith, because you can't remember for which methods the underscore is necessary to improve readability.

Also, if you want to follow PEP 8, you should change your first post to note that underscores are not required.
Craig "Ichabod" O'Brien
Minimalist, buddhist, theist, and programmer
Current languages: Python, SAS, and C++
Previous serious languages: R, Java, VBA, Lisp, HyperTalk, BASIC
ichabod801
 
Posts: 84
Joined: Sat Feb 09, 2013 12:54 pm
Location: Outside Washington DC

Re: Naming Conventions (PEP 8)

Postby micseydel » Fri Feb 22, 2013 9:06 pm

Ah, my mistake, modules versus function names.

I'm not going to argue about how Python should work, or whether it's ideal as-is. I'm not going to bug people about always using underscores or not. But I do still believe that consistency is generally good, although as we've discussed I don't personally care much about many of the things you've pointed out. I do feel strongly about CamelCase for classes, but much of what we discussed I'm flexible on.

Yeah, I'm going to edit the post to emphasize going for readability.
Join the #python-forum IRC channel on irc.freenode.net!
User avatar
micseydel
 
Posts: 939
Joined: Tue Feb 12, 2013 2:18 am
Location: Mountain View, CA

Re: Naming Conventions (PEP 8)

Postby KevinD » Mon Feb 25, 2013 10:44 pm

This one sentence is the key:
micseydel wrote:Consistency within an individual is important, but I believe their is value to consistency among everyone. It just makes reading things faster.


I have my own programming quirks that I follow - I end a lot of variable names with "_dt" if they are a date, or "_ct" if they count something, for example. I've been doing that for years, through different languages. It's not a rule or anything, but it helps me to follow my own code. I can go back to something I wrote several years ago, and see what the different variables mean. The code or the logic might be incomprehensible, but at least the variables won't be. I don't expect everyone to follow those guidelines; they're just something I do for myself.

A convention is what others expect me to follow - using camel case, semi-colons, white space, and things like that. If enough people follow the same guidelines, then it makes it easier for others to understand code they've never seen. I don't think anyone here will be chastised (too much, at least) for using a lower-case class name or for only indenting three spaces instead of four. Conventions are just things we've become accustomed to seeing, and saves a few minutes in trying to understand what someone else is trying to do.
Quanto lignum posset materiae materietur marmota Chuck si materiam possit materiari foedans, penitus lignum?
KevinD
 
Posts: 30
Joined: Fri Feb 08, 2013 3:15 am


Return to Tutorials

Who is online

Users browsing this forum: Google [Bot] and 1 guest