Skip to content

Latest commit

 

History

History
106 lines (77 loc) · 3.86 KB

README-code-quality.md

File metadata and controls

106 lines (77 loc) · 3.86 KB
Raw

Code Quality: Style Guide and Tests

Table of Contents

Style Guide

Code and checks in TokenSPICE should strive to follow:

  • PEP 8 Style Guide, PEP 20 The Zen of Python, PEP 484 Type Hints, PEP 257 Docstring conventions
  • And, most specifically, google docstring convention [2]. It's a good balance of compact, readable, and specific. Docstrings should include variable types if they are not explicitly type hints in code itself.
  • pydocstyle v4.0.0 supports google docstring convention [ref]. This means checks for all the errors except D203, D204, D213, D215, D400, D401, D404, D406, D407, D408, D409 and D413 .
def myfunction(param1, param2):
    """Example function with types documented in the docstring.

    `PEP 484`_ type annotations are supported. If attribute, parameter, and
    return types are annotated according to `PEP 484`_, they do not need to be
    included in the docstring:

    Args:
        address: str -- Eth address
        agents: set of Agent -- 
        agent_ages: dict of {agent_name:str : agent_age:int} -- agent's ages
	completed: list of int --

    Returns:
        bool: Success if True
    """

On Tests

Ensure that the local tests are the same as remote; otherwise we'd end up fixing things we don't care about.

Codacy supports testing across many tools at once. It's easy to run remotely. However to use locally, codacy-cli runs slowly and churns the CPU. There are so many unimportant tests that it obscures the important ones.

Therefore, we only use pylint. It's 80% of the benefit with 20% of the effort. Setup:

  • Locally: just use pylint, not codacy-cli
  • Remotely: use codacy, but only pylint is used
  • For both, ignore the checks D203, D204, etc as specified in the Style Guide above

Remote Tests

Codacy is automatically run remotely for each commit of each PR.

Local Tests

Use pylint. Here's a pylint tutorial..

Here's an example. In the terminal:

pylint *

Pylint auto-loads ./pylintrc and uses its options, such as ignoring D203, D204.

Example pylint output:

engine/SimEngine.py:9:0: W0611: Unused valuation imported from util (unused-import)
engine/AgentWallet.py:419:4: C0116: Missing function or method docstring (missing-function-docstring)
...
-----------------------------------
Your code has been rated at 8.07/10

To learn more about a complaint, some examples:

pylint --help-msg=unused-import
pylint --help-msg=missing-function-docstring

Local Fixes

There are a couple approaches to making fixes:

  1. Use automated tools like black
  2. Manually

We recommend to start with (1), then clean the rest with (2).

Usage of black on one file:

black netlists/simplepool/test/test_netlist.py

It will output:

reformatted netlists/simplepool/test/test_netlist.py
All done! ✨ 🍰 ✨
1 file reformatted.

For maximum productivity, use black on everything:

black ./