NuSpatial Python Style Guide

Linter

Pylint

• pylint is a tool for finding bugs and style problems in Python source code. It finds problems that are typically caught by a compiler for less dynamic languages like C and C++. Because of the dynamic nature of Python, some warnings may be incorrect; however, spurious warnings should be fairly infrequent.

Code Style

1. SEMICOLONS

   1. Don’t terminate lines with semi-colons and don’t use semi-colons to put two commands on the same line.

2. LINE LENGTH

   1. The maximum line length is 80 characters.

3. PARENTHESES

   1. Use parentheses sparingly.

      1. Don’t use them in return statements or conditional statements unless using parentheses for implied line continuation.

4. INDENTATION

   1. Indent your code blocks with 4 spaces. Never use tabs or mix tabs and spaces.

5. BLANK LINES

   1. Two blank lines between top-level definitions and one blank line between method definitions.

6. WHITESPACE

   1. Whitespace follows standard typographic rules for the use of spaces around punctuation.

      1. No whitespace inside parentheses, brackets, or braces.

      2. No whitespace before a comma, semi-colon or colon except at the end of line.

      3. No whitespace before the open paren/bracken that starts and argument list, indexing, or slicing.

      4. Surround binary operators with a single space on either side for assignment.

      5. Don’t use spaces around the = sign when used to indicate a keyword argument or a default parameter value.

      6. Don’t use spaces to vertically align tokens on consecutive lines.

7. SHEBANG LINE

   1. Most .py files do not need to start with a #! line. Start the main file of a program with #!/usr/bin/env python with an optional sing digit 2 or 3 suffix.

8. COMMENTS

   1. Be sure to use the right style for module, function, method and in-line comments.

9. CLASSES

   1. If a class inherits from no other base classes, explicitly inherit from object. This also applies to nested classes.

10. STRINGS

    1. Use the format method or the % operator for formatting strings, even when the parameters are all strings.

       1. Avoid using the + and += operators to accumulate a string within a loop.

       2. Be consistent with your choice of string quote character within a file. Pick ‘ or “ and stick with it.

11. FILES AND SOCKETS

    1. Explicitly close files and sockets when you are done with them. Leaving files, sockets or other file-like objects has several downsides.

    2. While files and sockets are automatically closed when the file object is destructed, tying the life-time of the file object to the state of the file is poor practice.

12. TODO COMMENTS

    1. Use TODO comments for code that is temporary, a short-term solution, or good-enough but not perfect.

    2. TODOS should include the string TODO in all caps, followed by the name, email address or other identifier of the person who can best provide context about the problem referenced by the TODO

13. IMPORTS FORMATTING

    1. Imports should be on separate lines.

    2. Imports are always put at the top of the file, just after any module comments and doc strings, but before module globals and constants.

    3. They should be grouped with the order of being most generic to least generic.

14. STATEMENTS

    1. Generally, only one statement per line. However, you may put the result of a test on the same line as the test only if the entire statement fits on one line.

15. ACCESS CONTROL

    1. If an accessor function would be trivial you should use public variables instead of accessor functions to avoid the extra cost of function calls in Python. When more functionality is added you can use the property to keep the syntax consistent.

16. NAMING

    1. Avoid single character names except for counters or iterators

    2. Avoid dashes (-) in any package/module name

    3. __double_leading_and_trailing_underscore__ names are reserved by Python.

    4. Internal" means internal to a module or protected or private within a class.

    5. Prepending a single underscore (_) has some support for protecting module variables and functions (not included with import * from). Prepending a double underscore (__) to an instance variable or method effectively serves to make the variable or method private to its class (using name mangling).

    6. Place related classes and top-level functions together in a module. Unlike Java, there is no need to limit yourself to one class per module.

    7. Use CapWords for class names, but lower_with_under.py for module names

17. MAIN

    1. Even a file meant to be used as a script should be importable and a mere import should not have the side effect of executing the script’s main functionality. The main fuctionality should be in a main() function

If you're editing code, take a few minutes to look at the code around you and determine its style. If they use spaces around all their arithmetic operators, you should too. If their comments have little boxes of hash marks around them, make your comments have little boxes of hash marks around them too.

For further reference see Google Python Style Guide