Règles de codage#
Règles de codage génériques#
Nous suivons le style de codage PEP 8.
En particulier, nous sommes particulièrement stricts sur les directives suivantes :
Limiter toutes les lignes à un maximum de 79 caractères.
Respecter les conventions de nommage (classes, fonctions, variables, etc.).
Utiliser des exceptions spécifiques au lieu de
Exception.
Pour faire respecter ces directives, les outils suivants sont obligatoires :
ruff pour le formatage du code et l’analyse statique du code.
pylint pour l’analyse statique du code.
ruff#
Si vous utilisez Visual Studio Code, les paramètres du projet formateront automatiquement votre code avec ruff à l’enregistrement (vous pouvez également exécuter la tâche « Run Ruff » pour exécuter ruff sur le projet).
Pour exécuter ruff, exécutez la commande suivante:
ruff check
pylint#
Pour exécuter pylint, exécutez la commande suivante:
pylint datalab
Si vous utilisez Visual Studio Code sur Windows, vous pouvez exécuter la tâche « Run Pylint » pour exécuter pylint sur le projet.
Note
Une note pylint supérieure à 9/10 est requise pour fusionner une demande d’extraction.
Règles de codage spécifiques#
En plus des directives de codage génériques, nous avons les directives spécifiques suivantes :
Écrire des docstrings pour toutes les classes, méthodes et fonctions. Les docstrings doivent suivre le style Google.
Ajouter des annotations de typage pour toutes les fonctions et méthodes. Les annotations doivent utiliser la syntaxe future (
from __future__ import annotations)Essayez de garder le code aussi simple que possible. Si vous devez écrire un morceau de code complexe, essayez de le diviser en plusieurs fonctions ou classes.
Ajouter autant de commentaires que possible. Le code doit être auto-explicatif, mais il est toujours utile d’ajouter des commentaires pour expliquer l’idée générale du code, ou pour expliquer certaines parties délicates.
N’utilisez pas d’instructions
from module import *, même dans le module__init__d’un package.Évitez d’utiliser des mixins (héritage multiple) si possible. Il est souvent possible d’utiliser la composition au lieu de l’héritage.
Évitez d’utiliser les méthodes
__getattr__et__setattr__. Ils sont souvent utilisés pour implémenter une initialisation paresseuse, mais cela peut être fait de manière plus explicite.