Dev: conventions de codage

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
+Windows. Créer une VM avec Debian 10, et suivre la
-d'installation de ScoDoc](GuideInstallDebian11.md).
+[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)
+- 

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)

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,
 <https://scodoc.org/git/ScoDoc/ScoDoc/src/branch/master/app/api/formsemestres.py#L91>):
 
 ```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)

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)