forked from ScoDoc/DocScoDoc
Dev: conventions de codage
This commit is contained in:
parent
40a6d54f76
commit
94d0644b9f
@ -13,8 +13,8 @@ aussi bien l'affaire).
|
||||
### Conseils pour la machine virtuelle
|
||||
|
||||
[VirtualBox](https://www.virtualbox.org/) est facile à installer sur Linux ou
|
||||
Windows. Créer une VM avec Debian 10, et suivre la [procédure habituelle
|
||||
d'installation de ScoDoc](GuideInstallDebian11.md).
|
||||
Windows. Créer une VM avec Debian 10, et suivre la
|
||||
[procédure habituelle d'installation de ScoDoc](GuideInstallDebian11.md).
|
||||
|
||||
Sur les Macs anciens (processeurs Intel), VirtualBox fonctionne bien. Sur les
|
||||
modèles "M1" (Apple Silicon), je conseille d'utiliser
|
||||
@ -81,7 +81,19 @@ VM, par exemple (adapter l'IP !):
|
||||
|
||||
### Partage de fichiers
|
||||
|
||||
Pour éditer votre code au chaud sur votre hôte, il y a plein de solutions.
|
||||
Pour éditer votre code au chaud sur votre hôte, il y a plein de solutions.
|
||||
La plus simple, déjà mentionnée, consiste à passer par une connexion SSH (VS
|
||||
Code propose un module dédié très simple et performant, mais tout montage de
|
||||
type `sshfs`peut aussi faire l'affaire).
|
||||
|
||||
|
||||
!!! note "Voir aussi"
|
||||
|
||||
- [Conventions de codage](DevConventions.md)
|
||||
- [API ScoDoc 9](ScoDoc9API.md)
|
||||
- [Guide installation](GuideInstallDebian11.md)
|
||||
- [Gestion des utilisateurs](AdminUsers.md)
|
||||
- [Guide administrateur ScoDoc](GuideAdminSys.md)
|
||||
- [FAQ](FAQ.md)
|
||||
- [Contacts](Contact.md)
|
||||
-
|
92
docs/DevConventions.md
Normal file
92
docs/DevConventions.md
Normal file
@ -0,0 +1,92 @@
|
||||
# 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)
|
@ -131,7 +131,7 @@ http GET http://localhost:5000/ScoDoc/api/formsemestres/query "Authorization:Bea
|
||||
|
||||
### Côté programmation serveur
|
||||
|
||||
Reprenons le même exemple (voir app/api/formsemestres.py ligne 91,
|
||||
Reprenons le même exemple (voir `app/api/formsemestres.py`` ligne 91,
|
||||
<https://scodoc.org/git/ScoDoc/ScoDoc/src/branch/master/app/api/formsemestres.py#L91>):
|
||||
|
||||
```py
|
||||
@ -177,6 +177,7 @@ lancer flask (plus rapide).
|
||||
|
||||
!!! note "Voir aussi"
|
||||
|
||||
- [Conventions de codage](DevConventions.md)
|
||||
- [Guide développeurs](GuideDeveloppeurs.md)
|
||||
- [API ScoDoc 9](ScoDoc9API.md)
|
||||
- [Modélisation du BUT](ModelisationParcoursBUT.md)
|
||||
|
@ -151,6 +151,7 @@ Note: la mise à jour par `apt` recrée le virtualenv à chaque fois.
|
||||
|
||||
!!! note "Voir aussi"
|
||||
|
||||
- [Conventions de codage](DevConventions.md)
|
||||
- [API ScoDoc 9](ScoDoc9API.md)
|
||||
- [Guide installation](GuideInstallDebian11.md)
|
||||
- [Gestion des utilisateurs](AdminUsers.md)
|
||||
|
Loading…
Reference in New Issue
Block a user