Styling + Documentation

[anitejb]

In the long term, we want to make sure that code is properly styled and commented to make it easier for developers to maintain and enhance.

Styling

To achieve this on our current codebase, we will use a combination of pylint and black.

pylint

• Useful for identifying issues such as import order, naming conventions, missing docstrings, etc.
• Doesn't actually make any changes, but provides a list of suggestions that can be made to improve the code
• All pylint codes can be found here

black

• Aggressive but useful for creating standardized code styling
• Automatically fixes issues such as files ending without newlines, single quotes instead of double quotes, trailing whitespace, etc.

In these instances where we feel like ignoring pylint warnings, or where pylint and black disagree, we will suppress pylint. These issues will be handled on a case-by-case basis.

Comments/Documentation

In general, Google's Python Style Guide is a great resource. Specifically, we will be using their guidelines on comments and docstrings to document our code. Again, this isn't set in stone - any disagreement with the styling conventions can be handled on a case-by-case basis.

Workflow

In general, the developer workflow should look a little like this:

write code
run black
run pylint
while pylint raises warnings:
    for warning in warnings:
        if warning is important:
            fix it
        else:
            suppress it
    run pylint
run black
push code

[anitejb]

Added to CONTRIBUTING.md with 81ca8c1