PEP Review

chapters/forms.tex

@@ -48,6 +48,7 @@ Ils agissent come une glue entre l'utilisateur et la modélisation de vos struct
 
 Tout comme pour le modèle (+ ref), l'idée est simplement de définir plusieurs niveaux de validation.
 
+
 \section{Gestion du changement}
 
 Dans le package \texttt{django.contrib.admin.utils}, on trouve une petite pépite du nom de \texttt{construct\_change\_message}.

chapters/new-project.tex

@@ -158,7 +158,10 @@ C'est en ça que consistent les \href{https://www.djangopackages.com/}{paquets D
 ce sont "\emph{simplement}" de petites applications empaquetées et pouvant être réutilisées dans différents contextes (eg. \href{https://github.com/tomchristie/django-rest-framework}{Django-Rest-Framework}, \href{https://github.com/django-debug-toolbar/django-debug-toolbar}{Django-Debug-Toolbar}, \ldots
 
 Le projet s'occupe principalement d'appliquer une couche de glue entre différentes applications.
-Une bonne pratique consiste à \textbf{limiter à cinq} le nombre de modèles différents dans chaque application.
+Découper proprement un projet en plusieurs applications totalement autonomes est illusoire.
+Une bonne pratique consiste à rester pragmatique et à partir avec \textbf{une seule} application, et la découper lorsque vous jugerez qu'elle grossit trop ou trop rapidement \cite[Rule \#5 : don't split files by default]{django_for_startup_founders} : découper trop rapidement et sans raison valable une application en plein de petits fichiers va gâcher énormément de temps de développement, sans apporter de réels bénéfices.
+D'autre part, une (autre) bonne pratique consiste à aussi \textbf{limiter à cinq} le nombre de modèles différents dans chaque application.
+Tant que ce seuil ne sera pas atteint, laissez ce principe de côté.
 
 \subsection{manage.py}
 

chapters/python.tex

@@ -115,6 +115,8 @@ Nous pouvons donc utiliser ces mêmes \textbf{dunder methods} (\textbf{double-un
 
 \section{The Zen of Python}
 
+(aussi connue sous PEP20 ;)) \index{PEP!PEP20}
+
 \begin{listing}[H]
 \begin{verbatim}
 	>>> import this
@@ -146,9 +148,23 @@ Nous pouvons donc utiliser ces mêmes \textbf{dunder methods} (\textbf{double-un
 
 \section{Guide de style}
 
-La première PEP qui va nous intéresser est la PEP8.
+La première PEP qui va nous intéresser est la PEP8. \index{PEP!PEP8}
 Elle spécifie comment du code Python doit être organisé ou formaté, quelles sont les conventions pour l'indentation, le nommage des variables et des classes, \ldots
+
 En bref, elle décrit comment écrire du code proprement, afin que d'autres développeurs puissent le reprendre facilement, ou simplement que votre base de code ne dérive lentement vers un seuil de non-maintenabilité.
+Comme l'indique la PEP20, \textit{Readibility counts}.
+Ceci implique de garder une cohérence dans l'écriture du code, dont les principales recommandations concernent:
+
+\begin{enumerate}
+	\item
+		\textbf{Le layout général} du code: indentation, longueur de ligne, séparateurs de lignes, encodage des fichiers sources et gestion des imports.
+	\item
+		\textbf{La gestion des commentaires}, en fonction de leur emplacement: blocs de commentaires, commentaires embarqués ou documentation.
+	\item
+		\textbf{Les conventions de nommage}: les noms à éviter, comment nommer une classe, une fonction ou une variable, un paquet, les exceptions ou les constantes.
+	\item
+		\textbf{Des recommandations de programmation}, concernant le typage statique \index{PEP!PEP484}
+\end{enumerate}
 
 Dans cet objectif, un outil existe et listera l'ensemble des conventions qui ne sont pas correctement suivies dans votre projet: flake8. Pour l'installer, passez par pip.
 Lancez ensuite la commande \texttt{flake8} suivie du chemin à analyser (\texttt{.}, le nom d'un répertoire, le nom d'un fichier \texttt{.py}, \ldots).
@@ -212,7 +228,7 @@ Il existe plusieurs types de balisages reconnus/approuvés:
 
 \ldots mais tout système de balisage peut être reconnu, sous réseve de respecter la structure de la PEP257.
 
-\subsection{PEP 257}
+\subsection{PEP 257} \index{PEP!PEP257}
 
 La \href{https://peps.python.org/pep-0257/#what-is-a-docstring}{PEP-257} nous donne des recommandations haut-niveau concernant la structure des docstrings: ce qu'elles doivent contenir et comment l'expliciter, sans imposer quelle que mise en forme que ce soit.
 de contenu, mais pas de forme, notamment sur la manière de représenter des docstrings ne nécessitant qu'une seule ligne, nécessitant plusieurs lignes ou de gérer l'indentation.
@@ -498,7 +514,7 @@ Cet élément peut être:
 
 \section{Formatage de code}
 
-Nous avons parlé ci-dessous de style de codage pour Python (PEP8), de style de rédaction pour la documentation (PEP257), d'un vérificateur pour nous indiquer quels morceaux de code doivent absolument être revus, \ldots
+Nous avons parlé ci-dessous de style de codage pour Python (PEP8) \index{PEP!PEP8}, de style de rédaction pour la documentation (PEP257) \index{PEP!PEP257}, d'un vérificateur pour nous indiquer quels morceaux de code doivent absolument être revus, \ldots
 Reste que ces tâches sont parfois (très) souvent fastidieuses: écrire un code propre et systématiquement cohérent est une tâche ardue.
 Heureusement, il existe plusieurs outils pour nous aider au niveau du formatage automatique.
 Même si elle n'est pas parfaite, la librairie \href{https://black.readthedocs.io/en/stable/}{Black} arrive à un très bon compromis entre
@@ -535,7 +551,7 @@ même forme, indépendamment du project sur lequel vous serez en train de
 travailler. L'étape de formatage deviendra transparente, et vous pourrez
 vous concentrer sur le contenu}".
 
-\section{Typage statique \index{PEP585}}
+\section{Typage statique \index{PEP!PEP484} \index{PEP!PEP585}}
 
 Nous vous disions ci-dessus que Python est un langage dynamique interprété.
 Concrètement, cela signifie que des erreurs qui auraient pu avoir été détectées lors de la phase de compilation, ne le sont pas avec Python.