Skip to content

Latest commit

 

History

History
80 lines (54 loc) · 3.92 KB

CONTRIBUTING.md

File metadata and controls

80 lines (54 loc) · 3.92 KB
Raw

Contributing guidelines

Before contributing

Welcome to poktinfo! Before sending your pull requests, make sure that you read the whole guidelines. If you have any doubt on the contributing guide, please feel free to state it clearly in an issue.

Contributing

Contribution

Pre-commit plugin

Use pre-commit to automatically format your code to match our coding style:

python3 -m pip install pre-commit  # only required the first time
pre-commit install

That's it! The plugin will run every time you commit any changes. If there are any errors found during the run, fix them and commit those changes. You can even run the plugin manually on all files:

pre-commit run --all-files --show-diff-on-failure

Coding Style

We want your work to be readable by others; therefore, we encourage you to note the following:

  • Please focus hard on the naming of functions, classes, and variables. Help your reader by using descriptive names that can help you to remove redundant comments.

    • Single letter variable names are old school so please avoid them unless their life only spans a few lines.
    • Expand acronyms because gcd() is hard to understand but greatest_common_divisor() is not.
    • Please follow the Python Naming Conventions so variable_names and function_names should be lower_case, CONSTANTS in UPPERCASE, ClassNames should be CamelCase, etc.

  • We encourage the use of Python f-strings where they make the code easier to read.

  • Please consider running psf/black on your Python file(s) before submitting your pull request. This is not yet a requirement but it does make your code more readable and automatically aligns it with much of PEP 8. There are other code formatters (autopep8, yapf) but the black formatter is now hosted by the Python Software Foundation. To use it,

    python3 -m pip install black  # only required the first time
black .

  • All submissions will need to pass the test flake8 . --ignore=E203,W503 --max-line-length=88 before they will be accepted so if possible, try this test locally on your Python file(s) before submitting your pull request.

    python3 -m pip install flake8  # only required the first time
flake8 . --ignore=E203,W503  --max-line-length=88 --show-source

  • Original code submission require docstrings or comments to describe your work.

  • More on docstrings and comments:

    The following are considered to be bad and may be requested to be improved:

    x = x + 2	# increased by 2

    This is too trivial. Comments are expected to be explanatory. For comments, you can write them above, on or below a line of code, as long as you are consistent within the same piece of code.

    We encourage you to put docstrings inside your functions but please pay attention to the indentation of docstrings. The following is a good example:

    def sum_ab(a, b):
    """
    Return the sum of two integers a and b.
    """
    return a + b

    The use of Python type hints is encouraged for function parameters and return values.

    def sum_ab(a: int, b: int) -> int:
    return a + b

  • List comprehensions and generators are preferred over the use of lambda, map, filter, reduce but the important thing is to demonstrate the power of Python in code that is easy to read and maintain.

  • If you need a third-party module that is not in the file requirements.txt, please add it to that file as part of your submission.