\documentclass[a4paper,10pt]{article}
\usepackage{myXsim}
\usepackage{minted}

\author{Benjamin Bertrand}
\title{Fonctions spécifications et tests - Cours}
\date{décembre 2022}

\pagestyle{empty}

\begin{document}

\maketitle

\setcounter{section}{1}
\section{Documenter}

Programmer c'est écrire du code pour que la machine le comprenne mais aussi et surtout pour que d'autres personnes le comprenne et soit en mesure de l'utiliser ou le modifier. C'est pour cela qu'il est primordiale de \textbf{documenter} les fonctions.

\begin{definition}[ Les docstrings ]

    Une \textbf{docstring} (chaine de documentation) est la manière choisi pour documenter les fonctions en Python. Elles se placent en dessous de la signature de la fonction (ligne avec \mintinline{python}{def}) et sont entourés de \mintinline{python}{""" ... """}.

    \begin{center}
        \begin{minipage}{0.5\linewidth}
            \begin{minted}[bgcolor=base3,linenos]{python}
def nom_de_la_fonction(argument1, argument2, ...):
    """ Explication du fonctionnement de la fonction """
    instruction 1
    instruction 2
    instruction 3
    ...
    return valeur
            \end{minted}
        \end{minipage}
    \end{center}

    Pour accéder à la docstring, on utilise l'attribut \mintinline{python}{__doc__} ou la fonction \mintinline{python}{help} en mode interactif.
    \begin{center}
        \begin{minipage}{0.5\linewidth}
            \begin{minted}[bgcolor=base3,linenos]{python}
>>> from math import sqrt
>>> print(sqrt.__doc__)
Return the square root of x.
            \end{minted}
        \end{minipage}
    \end{center}
\end{definition}


\section{Tester}

Écrire une fonction qui marche c'est bien mais écrire une fonction qui fait ce qu'on attend d'elle c'est mieux. Pour s'assurer qu'une fonction a comportement attendu, il faut écrire des \textbf{tests} en utilisant le mot clé \mintinline{python}{assert}.
\begin{center}
    \begin{minipage}{0.5\linewidth}
        \begin{minted}[bgcolor=base3,linenos]{python}
assert condition
        \end{minted}
    \end{minipage}
\end{center}

Si la condition est vérifiée rien ne se passera. Par contre, si elle est fausse, une erreur sera remontée.


\paragraph{Exemple}
\begin{center}
    \begin{minipage}{0.5\linewidth}
        \begin{minted}[bgcolor=base3,linenos]{python}
def mention(note):
    """ Renvoie la mention qui correspond à la note"""
    if note >= 16:
        return "TB"
    elif note >= 14:
        return "B"
    elif note >= 12:
        return "AB"
    elif note >= 9:
        return "A"
    else:
        return "R"

assert mention(13) == "AB"
assert mention(18) == "TB"
assert mention(9.5) == "R"
        \end{minted}
    \end{minipage}
\end{center}
Les deux premiers tests passent. Par contre, le dernier rate car nous avons fait une erreur dans la programmation de la fonction.

\paragraph{Remarques:} Écrire les tests avant de coder la fonction est considéré comme une bonne pratique.


\end{document}
