MAJ conventions codage

This commit is contained in:
Emmanuel Viennet 2024-07-22 16:40:22 +03:00
parent 5f44559b76
commit 8e5f8684f7

View File

@ -16,20 +16,22 @@ Pour les nouveaux codes, respecter les principes suivants:
conduit à dupliquer du code (qui existe en général dans le serveur) et
augmente les coûts de maintenance.
## Formatage du code
## Conventions de codage
### 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 espaces (sous VS Code, utiliser *Prettier*).
## Conventions standard Python
### 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
### Annotations de type (typehints)
On annote les paramètres et résultats des fonctions.
@ -40,9 +42,9 @@ def _upload_justificatif_files(
...
```
## Vues et templates
## Pages et templates
Les vues utilisent un template *Jinja*, fichier avec extension j2.
Les vues utilisent un template *Jinja2*, fichier avec extension j2.
On s'astreint, sauf cas particulier, à un nommage identique de la route, la vue et du template.
@ -53,10 +55,69 @@ def un_exemple(...):
return render_template(".../un_exemple.j2")
```
Le template aura typiquement avec la structure suivante:
```jinja
{% extends "sco_page.j2" %}
{% block app_content %}
<h1>Titre</h1>
{% endblock app_content %}
```
Pour les pages dans un semestre (avec barre menu etc.), on utilisera `<h2>` au
lieu de `<h1>`.
### Templates habituels
Les templates suivants sont les plus utilisés pour les pages:
- `base.j2` pages hors département (accueil, configuration, ...)
- `sco_page.j2` page standard dans un formsemestre: avec sidebar et barre de
menu du semestre.
- `sco_dept_page.j2` page dans un département (avec sidebar) mais sans formsemestre (pas de
barre de menu)
### Constantes définies dans les templates ScoDoc
Le `context_processor` `inject_sco_utils()` ajoute des objets pour accès à tous
les templates ScoDoc:
- `scu` : le module `sco_utils.py` (diverses fonctions utilitaires et variables
de config.)
- `sco` : des données sur le contexte, notamment les préférences, le
formsemestre et l'étudiant courants (resp. `sco.formsemestre` et `sco.etud`)
### Appel d'un template page
Pour mémoire, l'appel d'un template dans une vue se fait ainsi:
```py
render_template( "votre_template.j2",
title="Changer de référentiel de compétences",
autre_variable=...
)
```
### Classes css
`scodoc.css` (et à partir de 9.7, `scodoc97.css`) définissent quelques classes à usage général:
- `div.scobox`: boite (bords arrondis, fond uni) regroupant des éléments.
- `div.scobox-title` le titre de la boite
- `div.scobox-buttons` boutons en bas de boite.
- `p.help`, `div.help`: explications, aide.
- ...
## 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
accès à la base se font à travers l'ORM *SQLAlchemy*. Les modèles sont définis
dans `app/models`, sauf les comptes utilisateurs qui sont dans
`/app/auth/models.py`.