Python Style Guide
For readability and maintainability, it’s critical to use a consistent coding style. The coding rules described in this document will help ensure that consistency.
Organize your computer code like you would a scientific paper.
- The largest unit of organization in a paper is the section (e.g., the “Results” section, the “Discussion” section, etc.).
- In code, a “section” is comprised of all program elements that share the same general purpose (e.g., string manipulation, user input, etc.).
- Each code section should be saved in a separate file. Organize your files in subdirectories to reflect the hierarchical organization of your code. In Python, that means using packages.
- In a scientific paper, sections are divided into subsections.
- In code, each class or definition in a given file is equivalent to a subsection.
- Typically there will be one class in each file, though in some cases multiple classes/definitions per file may be appropriate.
- In scientific writing, subsections are divided into paragraphs.
- In code, each of the definitions within a class are like a paragraph.
- Like a paragraph, the code in each definition should be focused on a single task (like a topic sentence).
- Paragraphs are made of sentences.
- In code, a “sentence” is a few commands that perform the same subtask.
- It’s not necessary to comment every line, but it is best to include a brief comment at the beginning of each code “sentence.”
Here’s an example in meta code:
File ("section"): StringDefinitions.code Class ("subsection"): Capitalization Definition ("paragraph"): TitleCase "Sentence" 1: # Comment: Make all the letters lower case. make_letters_lower_case_commands "Sentence" 2: # Comment: Make the first letter capital case. make_first_letter_capital_commands
- Tabs aren’t allowed. Instead, use four spaces.
- Blank lines are useful for separating different code sections.
- All code should end in a single blank line.
- Two blank lines should precede every class definition, as well as any top-level definition (not contained in a class). Otherwise, two consecutive blank lines are not allowed.
- Lines can’t end in spaces.
- A space should follow every comma.
- Parentheses and square brackets aren’t padded with spaces.
( "a", "b" )
[ "a", "b" ]
- Certain characters must be flanked by spaces: + – < > =
5 + 3 = 8
5 > 3 - 1
3 < 5
- No line can be longer than 79 characters. Parentheses can often be used to split lines:
if (not line.startswith("var ") and not line.startswith("function ") and not line.startswith("window ") and not line.startswith("/*") and not line.startswith("*")): name = line.replace("(", " ") name = name.replace("=", " ") name = name.replace(":", " ").split()
Functions and Variables
- Function and variable names.
- In python, functions are named_like_this().
- Classes are named in TitleCase.
- All classes and functions must have docstrings. Class docstrings look like this:
class PythonChecker(Checker): """A class for checking python styling."""
Definition docstrings look like this:
def recursive_file_search(dirname, file_mask, exclude_strings = ): """A directory to resursively search for a file. Args: dirname (string): The directory. Can also be a file. file_mask (string): The file mask (e.g., *.py). exclude_strings ([string]): Optional. Any files containing these strings will be ignored. Defaults to . Returns: [string]: A list of the matching files. """
No script should run anything when imported. So unless your code is in a class or definition, place it in a conditional like this:
if __name__ == "__main__": # Python code here.