Dev: conventions de codage

This commit is contained in:
Emmanuel Viennet 2023-12-12 09:39:20 -03:00
parent 40a6d54f76
commit 94d0644b9f
4 changed files with 110 additions and 4 deletions

View File

@ -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
@ -85,3 +85,15 @@ 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)
-

92
docs/DevConventions.md Normal file
View File

@ -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)

View File

@ -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)

View File

@ -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)