DocScoDoc/docs/DevConventions.md

93 lines
3.1 KiB
Markdown

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