Réécrit le cours sur les fonctions python

src/cours/CIEL1/01-bases-python/cours/python-bases-3-fonctions.md

@@ -2,58 +2,185 @@
 
 ## Fonctions
 
-Vous connaissez déjà certaines fonctions, celles que vous avez utilisées lors du précédent TP : `print`, `input`, `range` ... Ce sont des fonctions que vous avez **appelées** mais qui existent déjà par défaut dans le langage Python.
+Vous connaissez déjà certaines fonctions, celles que vous avez utilisées lors du précédent TP : `print`, `input`, ... 
+Il en existe un très grand nombre, mais il est aussi très courant que les développeurs doivent écrire leurs propres fonctions.
+
+Qu'est-ce qu'une fonction ?
+
+```admonish success title="Définition"
+Une fonction exécute une suite d'instructions pour réaliser une action précise. Elle possède un nom par lequel on peut l'appeler, pour réaliser cette suite d'instructions.
+```
+
+Autrement dit, une fonction exécute un ensemble d'actions pré-enregistrées, auxquelles on a donné un nom pour pouvoir réaliser ces actions plus facilement, sans avoir à toujours les répéter.
 
 ### Appeler une fonction
 
-- Les fonction s'utilisent avec la syntaxe suivante : `nom_de_la_fonction(parametre_1, parametre_2, ...., parametre_n)`
+Appeler une fonction, c'est lui demander de faire la tâche pour laquelle elle a été conçue : exécuter les instructions qui la composent.
-    - Vous mettez le nom de la fonction, suivi de parenthèses
-    - Entre les parenthèses vous mettez les paramètres séparés par des virgules
-    - Si une fonction n'a pas besoin de paramètres, les parenthèses sont quand même indispensables.
 
-- Certaines fonctions peuvent prendre des paramètres nommés, avec la syntaxe suivante : `nom_de_la_fonction(nom_parametre=valeur_parametre)`. Les paramètres nommés sont toujours à la fin et leur ordre n'a pas d'importance.
+Les fonctions s'appellent avec la syntaxe suivante :
 
-- Une fonction peut renvoyer un résultat, que l'on peut alors affecter à une variable.
+```python
-- Si une fonction ne renvoie rien, alors elle renverra en réalité la valeur spéciale `None`.
+nom_de_la_fonction(parametre_1, parametre_2, ...., parametre_n)
-
-```admonish success title='À retenir'
-- Les fonctions servent à rendre votre code plus clair et mieux découpé. Elles permettent de réutiliser du code.
-- Pour déclarer une fonction en python :
-    ~~~python
-    def nom_de_la_fonction(parametre_1, parametre_2, ..., parametre_n):
-        # Instructions
-    ~~~
-    - On utilise le mot-clé `def` suivi du nom de la fonction. 
-    - Entre parenthèses on ajoute les paramètres qu'il faudra fournir
-    - À la fin de la ligne on met `:` (encore et toujours)
-    - On passe à la ligne suivante et on indente pour écrire les instructions.
-- Les paramètres fonctionnent comme des variables : on peut les utiliser dans la fonction avec leur nom.
-- On peut définir une valeur par défaut à un paramètre : il suffit d'écrire `parametre=valeur_par_defaut` lors de la déclaration. On peut alors omettre le paramètre, qui prendra automatiquement la valeur par défaut.
-- Deux fonctions ne peuvent pas avoir le même nom, sinon, la dernière a avoir été déclarée écrase la précédente.
 ```
 
-```admonish success title="À retenir"
+- Vous mettez le nom de la fonction, suivi de parenthèses
-- L'instruction `return` permet de sortir immédiatement d'une fonction. Rien ne s'exécutera après le `return`
+- Ce qui se trouve entre les parenthèses s'appelle les **paramètres** parfois appelés **arguments**
-- `return` permet de retourner un résultat, avec la syntaxe `return valeur`. Si aucune valeur n'est mentionnée, elle retournera `None`
+- On sépare les paramètres par une virgule
-- Si `return` n'est pas mentionnée, la fonction s'exécute jusqu'au bout et sortira à la fin du bloc d'instructions en retournant `None`
+- Si une fonction n'a pas besoin de paramètres, les parenthèses sont quand même indispensables.
-- On peut retourner plusieurs valeurs en les séparant par une virgule. 
+
-    - Ces valeurs peuvent être affectées à une seule variable sous forme d'un **tuple** (nous en parlerons au prochain TP)
+#### Paramètres
-    - Chaque valeur peut être affectée à une variable différente avec la syntaxe `variable_1, variable_2 ... = nom_de_la_fonction(...)`.
+
+Les paramètres sont des données que l'ont fournit à la fonction pour qu'elle puisse adapter son résultat à notre besoin.
+
+```admonish example title="Exemple"
+La fonction `print` affiche une chaîne de caractères. On lui passe la chaîne que l'on veut afficher en paramètre :
+~~~python
+# Pour afficher "Hello, World!", on passe en paramètre "Hello, World!" à print
+print("Hello, World!")
+~~~
 ```
 
-```admonish tip title='Bonnes pratiques'
+#### Paramètres nommés
+
+Certaines fonctions peuvent prendre des paramètres particuliers, nommés. C'est à dire qu'au lieu de se baser sur l'ordre des paramètres, on va écrire leur nom.
+
+Cela ressemblera à ça :
+```python
+nom_de_la_fonction(nom_parametre=valeur_parametre)
+```
+
+```admonish example title="Exemple"
+La fonction `print` sépare ses arguments avec des espaces. Si on donne une valeur au paramètre `sep`, on peut changer le caractère que `print` utilisera pour séparer les chaînes de caractères
+~~~python
+# Par défaut, print sépare les chaînes de caractères avec des espaces
+>>> print("foo", "bar")
+foo bar
+
+# Mais si on met sep='|', c'est le caractère '|' qui séparera les chaînes de caractères
+>>> print("foo", "bar", sep="|")
+foo|bar
+~~~
+```
+
+#### Retourner une valeur
+
+Une fonction peut renvoyer un résultat, que l'on peut alors affecter à une variable avec la syntaxe suivante :
+ ```python
+ma_variable = ma_fonction()
+```
+
+```admonish example title="Exemple"
+Si la fonction `add` fait la somme des nombres qu'on lui passe en paramètre :
+~~~python
+ma_variable = add(1, 3) # add fait 1 + 3 et retourne le résultat dans ma_variable
+# ma_variable vaut alors 4
+~~~
+```
+
+```admonish tip title="Remarque"
+Si une fonction ne renvoie rien, alors elle renverra en réalité la valeur spéciale `None`. 
+
+`None` est considérée comme `False` dans une condition
+```
+
+### Créer nos propres fonctions
+
+On va pouvoir regrouper des instructions que l'on souhaite répéter et créer des fonctions pour appeler toutes ces instructions avec un simple nom.
+Les fonctions servent à rendre votre code plus clair et mieux découpé. Elles permettent de réutiliser du code.
+
+Pour déclarer une fonction en python :
+```python
+def nom_de_la_fonction(parametre_1, parametre_2, ..., parametre_n):
+    # Ici on mettra les instructions indentées (décalées) 
+```
+- On utilise le mot-clé `def` suivi du nom de la fonction. 
+- Entre parenthèses on ajoute les paramètres qu'il faudra **fournir**
+- À la fin de la ligne on met `:` (encore et toujours)
+- On passe à la ligne suivante et **on indente** pour écrire les instructions.
+
+```admonish warning title="Attention"
+Deux fonctions ne peuvent pas avoir le même nom, sinon, la dernière a avoir été déclarée écrase la précédente.
+```
+
+#### Les paramètres
+A l'intérieur d'une fonction, les paramètres fonctionnent comme des variables : on peut les utiliser avec leur nom.
+
+```admonish example title="Exemple"
+On veut écrire une fonction `ma_fonction` qui affiche deux nombres, puis on l'appelle avec les nombres 2 et 5
+~~~python
+def add(a, b):
+    print(a)
+    print(b)
+
+add(2, 5)
+# Résultat affiché :
+# 2
+# 5
+~~~
+```
+
+##### Valeurs par défaut
+
+Les paramètres peuvent être optionnels. Pour cela, il faut qu'ils aient une **valeur par défaut**. 
+
+La valeur par défaut est la valeur que prend le paramètre si on ne lui en fournit aucune autre.
+
+```admonish example title="Exemple"
+~~~python
+def ma_fonction(parametre="valeur par défaut"):
+    print(parametre)
+
+ma_fonction()
+# Résultat affiché : valeur par défaut
+ma_fonction(parametre="Autre valeur")
+# Résultat affiché : Autre valeur
+~~~
+```
+
+#### L'instruction `return`
+
+L'instruction `return` permet deux choses :
+- Sortir immédiatement de la fonction
+- Si on lui fournit une valeur, la fonction **renvoie** cette valeur (sinon, elle renvoie la valeur spéciale `None`)
+
+```admonish example title="Exemple"
+La fonction `add` additionne les deux nombres passé en paramètre
+~~~python
+def add(a, b):
+    somme = a + b
+    return somme
+~~~
+```
+
+#### Bonnes pratiques
+
 - Faites des fonctions courtes qui vont à l'essentiel (20 lignes est un bon maximum)
 - Choisissez bien les noms de vos fonctions et de vos paramètres pour qu'ils soient clairs et explicites
+- Faites en sorte que vos fonctions fassent une seule tâche (qui peut nécessiter plusieurs instructions, bien évidemment !)
 - Vous pouvez documenter vos fonctions à l'aide d'une **docstring** : après l'en-tête de la fonction, avant le bloc d'instructions vous pouvez écrire une chaîne de caractères qui commence par 3 `"` ou `'`. 
     Exemple:
-    ~~~python
+    ```python
     def ma_fonction(arg_1, arg2):
         """Ceci est une docstring qui vient documenter ma fonction.
-        Une docstring peut prendre plusieurs lignes.
+
+        Une docstring peut prendre plusieurs lignes. Une bonne docstring vient expliquer les arguments
+        et ce que renvoie la fonction.
+
+        Parameters
+        ----------
+        arg_1 : Any
+            Argument d'exemple
+        arg_2 : Any
+            Autre argument d'exemple
+
+        Returns
+        -------
+        bool
+            Retourne un booléen pour l'exemple
         """
         # Bloc d'instructions
-    ~~~
+        return True
-```
+    ```
 
 
 # Annexes