Style & Formatting

Style & Formatting

This section outlines OtterTune's style/formatting guidelines and helper scripts.

Style Guides

We use Google's style/format conventions:

• Google Python Style Guide
• Google Java Style Guide

Source Validator Script

We provide a source code validation script that performs the following checks:

• check_pylint: Runs pylint on the python source code

• check_pycodestyle: Runs pycodestyle on the python source code

• check_illegal_patterns: Checks that the source code does not use any illegal statements (e.g., print)

• check_header: Checks that all source files have the correct header

Our source validation script returns 0 on success and -1 on failure. We execute this script on travis-ci so failing any of its checks will also cause the travis-ci build to fail.

Usage (python script/validators/source_validator.py -h):

usage: source_validator.py [-h] [--staged-files] [PATH [PATH ...]]

Validate OtterTune's source code

positional arguments:
  PATH            Files or directories to (recursively) validate

optional arguments:
  -h, --help      show this help message and exit
  --staged-files  Apply the selected action(s) to all staged files (git)

Usage examples:

python script/validators/source_validator.py  # validates all source files in the ottertune repo

python script/validators/source_validator.py server/analysis server/website/fabfile.py  # validates all files in the analysis directory and fabfile.py

python script/validators/source_validator.py --staged-files  # validates all files staged for commit (git)

Formatter Script

We provide a formatting script that automatically formats source code files and adds headers. For python, it uses the autopep8 module to fix the formatting. Note that since autopep8 uses pycodestyle to detect the style errors it should fix all (or most) of them; however, it does not use pylint so it may not fix all of its reported errors.

Usage(python script/formatting/formatter.py -h):

usage: formatter.py [-h] [--no-update-header] [--no-format-code]
                    [--staged-files]
                    [PATH [PATH ...]]

Formats python source files in place

positional arguments:
  PATH                Files or directories to (recursively) apply the actions
                      to

optional arguments:
  -h, --help          show this help message and exit
  --no-update-header  Do not update the source file headers
  --no-format-code    Do not format the source files use autopep8
  --staged-files      Apply the selected action(s) to all staged files (git)

Pylint

We use pylint to help analyze our source code using a custom configuration file.

To run pylint on its own, use: pylint --rcfile=script/formatting/config/pylintrc [file_path]

Pylint does a thorough analysis on the source code. But sometimes it reports false errors. Other times, you might want pylint to ignore a specific error on some line of code.

To disable an error message on a particular line of code, you can add an inline comment of the form: # pylint: disable=[message-code].

In the example below, pylint is outputing a (false) message that os.walk(dir_path) is not iterable. We disable it using the not-an-iterable message code:

def format_dir(dir_path, update_header, format_code):
    for subdir, _, files in os.walk(dir_path):  # pylint: disable=not-an-iterable
        for file_path in files:
            file_path = subdir + os.path.sep + file_path
            format_file(file_path, update_header, format_code)