forked from ScoDoc/DocScoDoc
93 lines
3.1 KiB
Markdown
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)
|