Fix references & complete Python chapter
continuous-integration/drone/push Build is failing Details

This commit is contained in:
Fred Pauchet 2022-04-12 19:18:05 +02:00
parent 32e8fc9ada
commit c4ebdaa48b
3 changed files with 38 additions and 23 deletions

View File

@ -119,7 +119,7 @@ sont jamais qu'une définition d'implémentation des frontières, dans la
mesure où un service n'est jamais qu'une fonction appelée au travers
d'un protocole (rest, soap, \ldots\hspace{0pt}). Une application
monolotihique sera tout aussi fonctionnelle qu'une application découpée
en microservices. \cite[243]{clean_architecture}
en microservices. \cite[p. 243]{clean_architecture}
\section{Inversion de dépendances}

View File

@ -212,21 +212,16 @@ Si vous ne voulez pas être dérangé sur votre manière de coder, et que vous v
Python étant un langage interprété fortement typé, il est plus que conseillé, au même titre que les tests unitaires que nous verrons plus bas, de documenter son code.
Cela impose une certaine rigueur, mais améliore énormément la qualité, la compréhension et la reprise du code par une tierce personne.
Cela implique aussi de \textbf{tout} documenter: les modules, les paquets, les classes, les fonctions, méthodes, \ldots\hspace{0pt}
Ce qui peut également aller à contrecourant d'autres pratiques \cite[53-74]{clean_code}; il y a une juste
mesure à prendre entre "tout documenter" et "tout bien documenter":
Cela implique aussi de \textbf{tout} documenter: les modules, les paquets, les classes, les fonctions, méthodes, ...
Ce qui peut également aller à contrecourant d'autres pratiques \cite{clean_code}{53-74} ; il y a une juste mesure à prendre entre "tout documenter" et "tout bien documenter":
\begin{itemize}
\item
Inutile d'ajouter des watermarks, auteurs, \ldots\hspace{0pt} Git ou
tout VCS s'en sortira très bien et sera beaucoup plus efficace que
n'importe quelle chaîne de caractères que vous pourriez indiquer et
qui sera fausse dans six mois,
Inutile d'ajouter des watermarks, auteurs, ...
Git ou tout VCS s'en sortira très bien et sera beaucoup plus efficace que n'importe quelle chaîne de caractères que vous pourriez indiquer et qui sera fausse dans six mois,
\item
Inutile de décrire quelque chose qui est évident; documenter la
méthode \texttt{get\_age()} d'une personne n'aura pas beaucoup
d'intérêt
Inutile de décrire quelque chose qui est évident; documenter la méthode \mintinline{python}{get_age()} d'une personne n'aura pas beaucoup d'intérêt
\item
S'il est nécessaire de décrire un comportement au sein-même d'une
fonction, c'est que ce comportement pourrait être extrait dans une
@ -249,16 +244,37 @@ Il existe plusieurs types de conventions de documentation:
\ldots\hspace{0pt}
\end{enumerate}
Les
\href{https://google.github.io/styleguide/pyguide.html\#38-comments-and-docstrings}{conventions
proposées par Google} nous semblent plus faciles à lire que du
RestructuredText, mais sont parfois moins bien intégrées que les
docstrings officiellement supportées (par exemple,
\href{https://clize.readthedocs.io/en/stable/}{clize} ne reconnait que
du RestructuredText;
\href{https://docs.djangoproject.com/en/stable/ref/contrib/admin/admindocs/}{l'auto-documentation}
de Django également). L'exemple donné dans les guides de style de Google
est celui-ci:
\subsection{PEP 257}
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.
Son objectif est d'arriver à une forme de cohérence lorsqu'un utilisateur souhaitera accéder à la propriété
Elle contient des conventions, pas des règles ou
\begin{quote}
“A universal convention supplies all of maintainability, clarity, consistency, and a foundation for good programming habits too. What it doesnt do is insist that you follow it against your will. Thats Python!”
-- Tim Peters on comp.lang.python, 2001-06-16
\end{quote}
Ainsi, les conventions sont décrites; chaque format propose ensuite son propre balisage (ReStructuredText, Numpy, Napoleon, ...).
A priori, vous pourriez tout à fait utiliser le vôtre, sous réserve que les conventions de la PEP-257 soient respectées.
\subsection{RestructuredText}
\href{https://peps.python.org/pep-0287/}{See also ;)}
\href{https://peps.python.org/pep-0258/}{See also}
\subsection{Numpy}
A remplir
\subsection{Napoleon}
Les \href{https://google.github.io/styleguide/pyguide.html\#38-comments-and-docstrings}{conventions proposées par Google} nous semblent plus faciles à lire que du RestructuredText, mais sont parfois moins bien intégrées que les docstrings officiellement supportées (par exemple, \href{https://clize.readthedocs.io/en/stable/}{clize} ne reconnait que du RestructuredText; \href{https://docs.djangoproject.com/en/stable/ref/contrib/admin/admindocs/}{l'auto-documentation} de Django également).
L'exemple donné dans les guides de style de Google est celui-ci:
\begin{listing}[!ht]
\begin{minted}{python}

View File

@ -6,8 +6,7 @@
year = {2018},
type = {Book}
}
@book{
other_side,
@book{other_side,
author = {Aurélie Jean},
title = {De l'autre côté de la machine},
year = {2020},