From 94d0644b9f346370333818b9507fbfc452e51b81 Mon Sep 17 00:00:00 2001 From: viennet Date: Tue, 12 Dec 2023 09:39:20 -0300 Subject: [PATCH] Dev: conventions de codage --- docs/ConseilServeurDev.md | 18 ++++++-- docs/DevConventions.md | 92 +++++++++++++++++++++++++++++++++++++++ docs/DevInternals.md | 3 +- docs/GuideDeveloppeurs.md | 1 + 4 files changed, 110 insertions(+), 4 deletions(-) create mode 100644 docs/DevConventions.md diff --git a/docs/ConseilServeurDev.md b/docs/ConseilServeurDev.md index 14b771d67..3c6edfb09 100644 --- a/docs/ConseilServeurDev.md +++ b/docs/ConseilServeurDev.md @@ -13,8 +13,8 @@ aussi bien l'affaire). ### Conseils pour la machine virtuelle [VirtualBox](https://www.virtualbox.org/) est facile à installer sur Linux ou -Windows. Créer une VM avec Debian 10, et suivre la [procédure habituelle -d'installation de ScoDoc](GuideInstallDebian11.md). +Windows. Créer une VM avec Debian 10, et suivre la +[procédure habituelle d'installation de ScoDoc](GuideInstallDebian11.md). Sur les Macs anciens (processeurs Intel), VirtualBox fonctionne bien. Sur les modèles "M1" (Apple Silicon), je conseille d'utiliser @@ -81,7 +81,19 @@ VM, par exemple (adapter l'IP !): ### Partage de fichiers -Pour éditer votre code au chaud sur votre hôte, il y a plein de solutions. +Pour éditer votre code au chaud sur votre hôte, il y a plein de solutions. La plus simple, déjà mentionnée, consiste à passer par une connexion SSH (VS Code propose un module dédié très simple et performant, mais tout montage de type `sshfs`peut aussi faire l'affaire). + + +!!! note "Voir aussi" + + - [Conventions de codage](DevConventions.md) + - [API ScoDoc 9](ScoDoc9API.md) + - [Guide installation](GuideInstallDebian11.md) + - [Gestion des utilisateurs](AdminUsers.md) + - [Guide administrateur ScoDoc](GuideAdminSys.md) + - [FAQ](FAQ.md) + - [Contacts](Contact.md) +- \ No newline at end of file diff --git a/docs/DevConventions.md b/docs/DevConventions.md new file mode 100644 index 000000000..c9cc42433 --- /dev/null +++ b/docs/DevConventions.md @@ -0,0 +1,92 @@ +# Conventions de codage pour ScoDoc + +Le projet étant très ancien, le code est passé par différentes conventions et +frameworks. Le style de python et celui du *frontend* web ont considérablement +évolués ces dernières décennies. + +Pour les nouveaux codes, respecter les principes suivants: + +- ScoDoc est avant tout une application serveur écrite en Python, qui offre des + services via une interface Web, une API, et accessoirement la ligne de + commande unix. + +- Les pages Web générées doivent l'être en Python côté serveur. On peut utiliser + du JS pour les pages dynamiques complexes (eg éditeur de partition) mais + éviter d'utiliser du JS pour générer des éléments statiques: l'abus de JS + conduit à dupliquer du code (qui existe en général dans le serveur) et + augmente les coûts de maintenance. + +## Formatage du code + +- l'usage de **[black](https://black.readthedocs.io/en/stable/)** est obligatoire +- l'usage de pylint et mypy est fortement recommandé +- Pour le code JS, indentation avec 2 espace (sous VS Code, utiliser Prettier). + +## Conventions standard Python + +On se tient à la PEP8, c'est à dire en résumé: +`UneClasse`, `une_fonction`, `_une_fonction_privee`, `une_variable`, `UNE_CONSTANTE_GLOBALE`. + +Les noms de fichiers sont en minuscules sans accents ni espaces, `comme_ceci.py`. + +## Annotations de type + +On annote les paramètres et résultats des fonctions. + +```py +def _upload_justificatif_files( + just: Justificatif, form: AjoutJustificatifEtudForm +) -> bool: + ... +``` + +## Vues et templates + +Les vues utilisent un template Jinja, fichier avec extension j2. + +On s'astreint, sauf cas particulier, à un nommage identique de la route, la vue et du template. + +```py +@bp.route("/un_exemple") +def un_exemple(...): + ... + return render_template(".../un_exemple.j2") +``` + +## Accès à la base de donnée + +Sauf exception (requêtes exotiques, problèmes de performance) à discuter, les +accès à la base se font à travers l'ORM *SQLAlchemy*. Mes modèles sont définis +dans `app/models`, sauf les comptes utilisateurs qui sont dans +`/app/auth/models.py`. + +Au moment de la définition de nouveaux modèles, éviter si possible les champs +*nullables*, penser à créer là où ce sera utile des index. + +## Tableaux + +ScoDoc génère beaucoup de tableaux, sauf exception destinés à l'affichage Web et à l'export xlsx. + +On utilise la super-classe `Table` de `app/tables/table_builder.py`. + +Le rendu HTML utilise *DataTables*. + +## Dates et heures + +ScoDoc, contrairement à de nombreuses applications, est centré sur les +*étudiants* et les enseignements, qui sont censés opérer dans le fuseau horaire +du serveur. Cela signifie que, quelle que soit l'emplacement de l'utilisateur, +les heures affichées et saisies par ScoDoc seront données dans le fuseau horaire +du serveur. + +L'API publie et reçoit des heures avec fuseau horaire (*timezone*) et n'est pas +concernée par cette remarque. + + +!!! note "Voir aussi" + + - [Introduction au développement ScoDoc](DevInternals.md) + - [Guide développeurs](GuideDeveloppeurs.md) + - [API ScoDoc 9](ScoDoc9API.md) + - [Modélisation du BUT](ModelisationParcoursBUT.md) + - [Contacts](Contact.md) diff --git a/docs/DevInternals.md b/docs/DevInternals.md index 4ef9b39a5..dfb9a7dce 100644 --- a/docs/DevInternals.md +++ b/docs/DevInternals.md @@ -131,7 +131,7 @@ http GET http://localhost:5000/ScoDoc/api/formsemestres/query "Authorization:Bea ### Côté programmation serveur -Reprenons le même exemple (voir app/api/formsemestres.py ligne 91, +Reprenons le même exemple (voir `app/api/formsemestres.py`` ligne 91, ): ```py @@ -177,6 +177,7 @@ lancer flask (plus rapide). !!! note "Voir aussi" + - [Conventions de codage](DevConventions.md) - [Guide développeurs](GuideDeveloppeurs.md) - [API ScoDoc 9](ScoDoc9API.md) - [Modélisation du BUT](ModelisationParcoursBUT.md) diff --git a/docs/GuideDeveloppeurs.md b/docs/GuideDeveloppeurs.md index c95c42452..b2fbd54f0 100644 --- a/docs/GuideDeveloppeurs.md +++ b/docs/GuideDeveloppeurs.md @@ -151,6 +151,7 @@ Note: la mise à jour par `apt` recrée le virtualenv à chaque fois. !!! note "Voir aussi" + - [Conventions de codage](DevConventions.md) - [API ScoDoc 9](ScoDoc9API.md) - [Guide installation](GuideInstallDebian11.md) - [Gestion des utilisateurs](AdminUsers.md)