# Design standard

## Imports

Allowed imports in production code is listed below.

- Built-in packages.
- Third party packages.
- Libraries.

If you need a function from another executable script, refactor it into a library and import it from both places.

Allowed imports in test code is listed below.

- Built-in packages.
- Third party packages.
- Test libraries.
- Functions from the code that is being tested.

Use to full path when importing.

## Style Guides

- The source code should follow [PEP-8](https://www.python.org/dev/peps/pep-0008/).
  - Exceptions to these rules are defined in the `tox.ini` or `<module>/tox.ini` and `.pylintrc` or `<module>/.pylintrc` files.
- Docstring documentation shall be done according to [PEP257 style guide](https://www.python.org/dev/peps/pep-0257/).

## Style Guide Verification

Test that the code is following the PEP-8 standards using
[flake8](https://pypi.org/project/flake8/) by running `flake8 <module>` and
[pylint](https://www.pylint.org/) by running `pylint <module>`.

The ignored folders should have their own configurations, to keep some kind of standard.

Plugins that should be used with flake8:

- flake8-docstrings

## Comments

Comments inside the code (not docstrings) should explain WHY something is implemented the way it is, not WHAT the implementation does.
An exception to this rule is regular expressions, which can be documented (but shall always be tested).

Instead of commenting about what the code does, write relevant tests that shows this.

Commented and unused code shall be removed.

## Executable scripts

All python scripts that are executed as stand-alone scripts should be located in the `<module>` in the project root folder.
The executable scripts shall use argparse if any argument is needed for the execution of the script.

## Libraries

Common code should be located in the `<module>/lib` folder.
If a library is only used by other libraries, it is allowed to put the files in a `<module>/lib/<library>` folder.

If the libraries requires arguments, they shall not be set as required in argparse.
Instead, they shall have a check to see if they are present when needed.
This is to make it easier to import the libraries if they are sometimes but not always using the library.

The library folders should all have an `__init__.py` containing doc string.

Placement of functions:

- If a function from an executable script is needed elsewhere, refactor it into a library and import it from both places.
- Only functions used by the library itself, functions that uses the library or functions used by more than one script should be in a library.
- Do not move a function to a library because you think it will be used by other scripts later.
  Wait until you can refactor both scripts to use the function.

## Tests

All tests shall be located in the `tests` folder.
Unit tests shall be named `test_<submodule>.py` and function tests shall be named `func_<submodule>.py`.
Example: `lib/gerrit.py` shall have a `tests/<module>/test_gerrit.py`.

Additional files needed by the tests shall be located in a separate folder: `test_data`.

The test shall test WHAT the module is doing, not HOW.
That means that you shall test as many public functions as possible, but do not explicitly test private functions (def `__<function>`).
Instead of testing the private functions, test the public functions in such a way that the private functions are being tested as well.
This makes it much easier to refactor how the code is implemented while keeping tests for what it does unmodified.

Some duplication of code is acceptable in the test code,
as this should be more focused on DAMP (Descriptive And Meaningful Phrases) than DRY (Don't repeat yourself) code.
While we want both, it sometimes makes the test code hard to read, and then DAMP should be prioritized in the test code.

Mocking inside of unit tests shall be limited to external systems (such as gerrit), and other processes (such as matlab).
Mocking inside of function tests shall be limited to external systems (such as gerrit).

The code shall be unit tested using the python package unittest.
The unit tests are run by `pytest.exe /\*\*/test\_\*.py` in the project root folder.
The function tests are run by `pytest.exe /\*\*/func\_\*.py` in the project root folder.
All tests can be run by `python -m unittest discover -s`.