Fix references & complete Python chapter
continuous-integration/drone/push Build is failing
Details
continuous-integration/drone/push Build is failing
Details
This commit is contained in:
parent
32e8fc9ada
commit
c4ebdaa48b
|
@ -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}
|
||||
|
||||
|
|
|
@ -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 doesn’t do is insist that you follow it against your will. That’s 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}
|
||||
|
|
|
@ -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},
|
||||
|
|
Loading…
Reference in New Issue