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 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.

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.

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

3.1 KiB Raw Blame History