| 1 |
.. _guidelines: |
| 2 |
|
| 3 |
Coding guidelines |
| 4 |
================= |
| 5 |
|
| 6 |
Generic coding guidelines |
| 7 |
------------------------- |
| 8 |
|
| 9 |
We follow the `PEP 8 <https://www.python.org/dev/peps/pep-0008/>`_ coding style. |
| 10 |
|
| 11 |
In particular, we are especially strict about the following guidelines: |
| 12 |
|
| 13 |
- Limit all lines to a maximum of 79 characters. |
| 14 |
- Respect the naming conventions (classes, functions, variables, etc.). |
| 15 |
- Use specific exceptions instead of the generic :class:`Exception`. |
| 16 |
|
| 17 |
To enforce these guidelines, the following tools are mandatory: |
| 18 |
|
| 19 |
- `ruff <https://pypi.org/project/ruff/>`_ for code formatting and static code analysis. |
| 20 |
- `pylint <https://pypi.org/project/pylint/>`_ for static code analysis. |
| 21 |
|
| 22 |
ruff |
| 23 |
^^^^ |
| 24 |
|
| 25 |
If you are using `Visual Studio Code <https://code.visualstudio.com/>`_, |
| 26 |
the project settings will automatically format your code with `ruff` on save |
| 27 |
(you may also run the task "Run Ruff" to run `ruff` on the project). |
| 28 |
|
| 29 |
To run `ruff`, run the following command:: |
| 30 |
|
| 31 |
ruff check |
| 32 |
|
| 33 |
pylint |
| 34 |
^^^^^^ |
| 35 |
|
| 36 |
To run `pylint`, run the following command:: |
| 37 |
|
| 38 |
pylint datalab |
| 39 |
|
| 40 |
If you are using `Visual Studio Code <https://code.visualstudio.com/>`_ |
| 41 |
on Windows, you may run the task "Run Pylint" to run `pylint` on the project. |
| 42 |
|
| 43 |
.. note:: |
| 44 |
|
| 45 |
A `pylint` rating greater than 9/10 is required to merge a pull request. |
| 46 |
|
| 47 |
Specific coding guidelines |
| 48 |
-------------------------- |
| 49 |
|
| 50 |
In addition to the generic coding guidelines, we have the following specific |
| 51 |
guidelines: |
| 52 |
|
| 53 |
- Write docstrings for all classes, methods and functions. The docstrings |
| 54 |
should follow the `Google style <https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings>`_. |
| 55 |
|
| 56 |
- Add typing annotations for all functions and methods. The annotations should |
| 57 |
use the future syntax (``from __future__ import annotations``) |
| 58 |
|
| 59 |
- Try to keep the code as simple as possible. If you have to write a complex |
| 60 |
piece of code, try to split it into several functions or classes. |
| 61 |
|
| 62 |
- Add as many comments as possible. The code should be self-explanatory, but |
| 63 |
it is always useful to add some comments to explain the general idea of the |
| 64 |
code, or to explain some tricky parts. |
| 65 |
|
| 66 |
- Do not use ``from module import *`` statements, even in the ``__init__`` |
| 67 |
module of a package. |
| 68 |
|
| 69 |
- Avoid using mixins (multiple inheritance) when possible. It is often |
| 70 |
possible to use composition instead of inheritance. |
| 71 |
|
| 72 |
- Avoid using ``__getattr__`` and ``__setattr__`` methods. They are often used |
| 73 |
to implement lazy initialization, but this can be done in a more explicit |
| 74 |
way. |