Code style

Please follow these coding standards when writing code for inclusion in BeeWare projects. Unless otherwise specified, follow PEP 8 (with careful attention paid to Section 2) Use flake8 to check for problems in this area. Remember that PEP 8 is only a guide, so respect the style of the surrounding code as a primary goal.

An exception to PEP 8 is our rules on line lengths. Don't limit lines of code to 79 characters if it means the code looks significantly uglier or is harder to read. We allow up to 119 characters as this is the width of GitHub code review; anything longer requires horizontal scrolling which makes review more difficult. This check is included when you run flake8. Documentation, comments, and docstrings should be wrapped at 79 characters, even though PEP 8 suggests 72.

  • Use four spaces for indentation.

  • Use four space hanging indentation rather than vertical alignment:

    raise AttributeError(
    'Here is a multine error message '
    'shortened for clarity.'
)

    Instead of:

    raise AttributeError('Here is a multine error message '
                     'shortened for clarity.')

    This makes better use of space and avoids having to realign strings if the length of the first line changes.

  • Use single quotes for strings, or a double quote if the the string contains a single quote. Don't waste time doing unrelated refactoring of existing code to conform to this style.

  • Avoid use of "we" in comments, e.g. "Loop over" rather than "We loop over".

  • Use underscores, not camelCase, for variable, function and method names

  • Use InitialCaps for class names (or for factory functions that return classes).

  • Use the Google Style Python Docstrings and PEP 257, type annotation with PEP 484 is optional.

    def function_with_types_in_docstring(param1, param2):
    """Example function with types documented in the docstring.

    Args:
        param1 (int): The first parameter.
        param2 (str): The second parameter.

    Returns:
        bool: The return value. True for success, False otherwise.

    """

    More examples of Google Docstrings

  • In test docstrings, state the expected behavior that each test demonstrates. Don't include preambles such as "Tests that" or "Ensures that".

  • Reserve ticket references for obscure issues where the ticket has additional details that can't be easily described in docstrings or comments. Include the ticket number at the end of a sentence like this:

    def test_foo():
    """A test docstring looks like this (#123456).
    """

Imports

Use isort to automate import sorting using the guidelines below.

Quick start:

$ pip install isort
$ isort -rc .

This runs isort recursively from your current directory, modifying any files that don't conform to the guidelines. If you need to have imports out of order (to avoid a circular import, for example) use a comment like this:

import module  # isort:skip

Put imports in these groups: standard library, third-party libraries, other BeeWare components, local BeeWare component, try/excepts. Sort lines in each group alphabetically by the full module name. Place all import module statements before from module import objects in each section. Use absolute imports for other BeeWare components and relative imports for local components.

On each line, alphabetize the items with the upper case items grouped before the lower case items.

Break long lines using parentheses and indent continuation lines by 4 spaces. Include a trailing comma after the last import and put the closing parenthesis on its own line.

Use a single blank line between the last import and any module level code, and use two blank lines above the first function or class.

Miscellaneous

Remove import statements that are no longer used when you change code. flake8 will identify these imports for you. If an unused import needs to remain for backwards-compatibility, mark the end of with # NOQA to silence the flake8 warning.

Systematically remove all trailing whitespaces from your code as those add unnecessary bytes, add visual clutter to the patches and can also occasionally cause unnecessary merge conflicts. Some IDE's can be configured to automatically remove them and most VCS tools can be set to highlight them in diff outputs.

Sign your work

Before we can merge your contribution into BeeWare, you need to give us permission to do so. Since you're an author of a creative work (a piece of code, or some documentation), you automatically own the copyright for that work. BeeWare can't legally use that contribution unless you give us permission to do so.

The BeeWare project uses a mechanism known as a Developer Certificate of Origin (DCO) to manage this process. The DCO is a legally binding statement that asserts that you are the creator of your contribution, and that you wish to allow BeeWare to use your work.

To indicate that you agree to the terms of the DCO, you just add a line to every git commit message:

Signed-off-by: Joe Smith <joe.smith@email.com>

If you set your user.name and user.email as part of your git configuration, you can sign your commit automatically with git commit -s.

If you have more questions about Developer Certificates of Origin, why they are required, what they mean, and how to configure your system to use them, see The Beginners Guide to DCOs, or get in touch with the core team.