A naming convention is a set of rules for choosing the character sequence used for identifiers which denote variables, types, functions, and other entities in source code and documentation.
Reasons for using a naming convention:
- to reduce the effort needed to read and understand source code
- to enhance source code appearance (for example, by disallowing overly long names or unclear abbreviations)
The choice of naming conventions can be an enormously controversial issue, with partisans of each holding theirs to be the best and others to be inferior. Colloquially, this is said to be a matter of “religion”. Many companies have also established their own set of conventions to best meet their interests.
Style Guide for Python Code¶
- code is read much more often than it is written
- consistency helps to improve the readability of code
- there are rules to produce consistency across the wide spectrum of Python code
Different levels of consistency in order of importance:
- Consistency within one module or function.
- Consistency within a project.
- Consistency with this style guide.
There are a lot of different naming styles. It helps to be able to recognize what naming style is being used, independently from what they are used for.
The following naming styles are commonly distinguished:
b(single lowercase letter)
B(single uppercase letter)
lowercase(all leters in lowercase)
st_mtime(prefix to group related names)
When using abbreviations in CamelCase, capitalize all the letters of the abbreviation. Thus
HTTPServerError is better than
Meaning of underscores¶
Single or double underscores at the beginning and/or at the end of names have special meanings in Python:
Weak “internal use” indicator. For example,
from M import *does not import objects whose name starts with an underscore.
Used by convention to avoid conflicts with Python keyword, e.g.
When naming a class attribute, invokes name mangling (inside class
“Magic” objects or attributes that live in user-controlled namespaces. E.g.
__file__. Never invent such names; only use them as documented.
Names to avoid¶
Never use the characters
l (lowercase letter el),
O (uppercase letter oh), or
I (uppercase letter eye) as single character variable names.
In some fonts, these characters are indistinguishable from the numerals one
1 and zero
0. When tempted to use
- class names should use
- constant names should be
- other names should use
- private variables/methods should start with an undescore:
- some special class methods are surrounded by two underscores:
Package and Module Names¶
Modules should have short, all-lowercase names. Underscores can be used if it improves readability.
Python packages should also have short, all-lowercase names, although the use of underscores is discouraged.
Almost without exception, class names use the CapWords (CamelCase) convention.
Classes for internal use have a leading underscore in addition.
Because exceptions should be classes, the class naming convention applies here. However, you should use the suffix “Error” on your exception names (if the exception actually is an error).
Global Variable Names¶
The conventions are about the same as those for functions.
Modules should use the
__all__ mechanism to prevent exporting globals, or use the older convention of prefixing such globals with an underscore.
Function names should be lowercase, with words separated by underscores as necessary to improve readability.
Function and method arguments¶
self for the first argument to instance methods.
cls for the first argument to class methods.
If a function argument’s name clashes with a reserved keyword, it is generally better to append a single trailing underscore rather than use an abbreviation or spelling corruption. Thus
class_ is better than
clss. (Perhaps better is to avoid such clashes by using a synonym.)
Method Names and Instance Variables¶
Use the function naming rules: lowercase with words separated by underscores as necessary to improve readability.
Use one leading underscore only for non-public methods and instance variables.
Constants are usually defined on a module level and written in all capital letters with underscores separating words. Examples: