DocAssiduites/docs/DevConventions.md

# 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 espaces (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 au format ISO 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)