Conventions de développement
Cette page établit une liste de contraintes à respecter pour que du code soit intégré à GestioCOF. Elles semblent nécessaires pour plusieurs raisons, comme l'amélioration de la lisibilité du code et une plus grande simplicité à travailler sur un projet collaboratif.
Ces contraintes ne devraient pas être des freins ! Si vous éprouvez des difficultés à les appliquer, placez votre attention sur la réalisation de votre but initial. Quelqu'un, ou vous-même, pourra toujours repasser un peu plus tard pour vous aider à peaufiner.
Ceratins des outils mentionnés ci-dessous peuvent être installés depuis gestioCOF avec:
pip install -r requiments-devel.txt
[[TOC]]
Linters
Commençons par les conventions les plus simples à respecter : celles mises en
œuvre par des programmes externes.
Ces outils peuvent généralement être intégrés facilement à votre éditeur de
texte, nativement parfois, par l'installation d'extensions sinon.
Une rapide recherche du nom de votre éditeur et de l'extension devrait vous
mettre sur une bonne voie.
Certains d'entre eux feront peut-être parties intégrantes du processus de
développement en étant ajoutés à la CI (intégration continue).
Pour savoir ce qu'il se passe dans la CI, consultez le dernier
gitlab-ci.yml
du projet.
black
black est le "uncompromising Python code formatter". Il applique des corrections pour rendre le code PEP8-compliant et va au-delà.
Les changements effectués sont déterministes et seront donc les mêmes peu importe la machine où il est utilisé. Les diffs des MRs s'en trouvent réduits et des conflits de fusion sont ainsi évités.
Pour formatter le code du projet entier, utilisez:
black .
Et sans effectuer de modifications mais en affichant les changements prévus:
black --check --diff .
Vous pouvez indiquer un ou plusieurs chemins en particulier:
black --check --diff bda/
Un hook git de pre-commit peut être installé (voir les instructions d'installation
de gestioCOF) pour formatter automatiquement vos modifications avec black.
Notez que black requiert la version 3.6 de Python au minimum.
Des modifications pourront être effectuéees au moment de commit, et devront
être ajoutées au contenu à commiter.
Si le programme n'est pas trouvé sur votre machine, ce check sera ignoré.
Attention cependant, l'intégration continue pourrait alors échouer, auquel cas
on peut vous aider.
isort
isort est aussi un formatter de code
Python, mais limité aux imports (from ... import ... et import ...).
Ces lignes suivent alors des règles de formatage identiques : tri par type
d'imports, alphabétique, etc.
À nouveau cela permet d'éviter des conflits de fusion.
Pour formatter le code du projet entier, utilisez:
isort --recursive bda cof gestioncof kfet provisioning shared utils
Ou seulement certains répertoires:
isort --recursive cof
Sans modifier les fichiers et en affichant les changements prévus:
isort --recursive --check-only --diff bda cof kfet
Ce formatter est aussi lancé par le hook de pre-commit (si le hook et isort
sont installés).
Des modifications pourront être effectuéees au moment de commit, et devront
être ajoutées au contenu à commiter.
Si le programme n'est pas trouvé sur votre machine, ce check sera ignoré.
Attention cepedant, l'intégration continue pourrait alors échouter, auquel cas
on peut vous aider.
flake8
Le code Python devrait être validé par flake8. Ce n'est pas une nécessité mais ça peut être une bonne habitude à prendre. Il vérifie, entre autres, que les conventions de la PEP8 sont bien respectées.
À noter : Django est testé avec flake8 et recommande son usage.
pylint
Bien que personne ne devrait vous en vouloir de ne pas rendre Pylint content, les messages offerts par ce plugin sont parfois utiles pour détecter des erreurs.