Docstrings are required for every function, class and method. No specific style is required. Though the Google docstring format is encouraged, we expect that most of the relevant information can be gleaned from both the function signature's type-hints and descriptive parameter names. The docstring should serve to give additional context/flavour beyond that which can be gained from the code itself.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29
Variable and parameter names should be as self-describing as possible. Brevity is not a concern here. Here are some common examples for writing good self-documenting code:
Single Letter Variable Names
1 2 3 4 5 6 7 8 9 10 11 12 13
Abbreviated Variable Names
1 2 3 4 5 6 7 8
Type Ambiguous Variable Names
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
Fidescls includes a
.pre-commit-config.yaml to facilitate running CI checks before pushing up to a PR. The
pre-commit package is included in the
dev-requirements.txt. Once that is installed, follow these steps to get up and running:
pre-commit install- This is a one-time setup step to create the git pre-commit hooks.
- These pre-commit hooks will now run automatically. However, you can also use
pre-commit runto run them manually once all of your changes have been staged.
NOTE: A Python interpreter must be available from wherever the git commands are being run, as this is required to run the
CI checks are stored as targets within the Makefile, and can be run from the top-level
fidescls directory with the following pattern:
1 2 3
Fidescls's code is formatted using the black style. This style is checked in a CI step, and merges to master are prevented if code does not conform.
A number of extensions are available for popular editors that will automatically apply black to your code.
Fidescls's code is linted using pylint. Linter checks run as part of a CI step and merges to master are prevented if code does not conform.
Fidescls's code is statically-typed using mypy. Type checking is validated as a CI step, and merges to master are prevented if code does not pass type checks. As a general rule, mypy typing requires all function arguments and return values to be annotated.
Fidescls's code is checked for its cyclomatic-complexity by Xenon. If a single logical piece of code is deemed too complex, then a CI step will fail, at which point the focus should be on breaking up said complex function/method/class.