S3-2 Documenter vos fonctions

I Les signatures dans la définition

La plupart des langages de programmation nécessitent la spécification du typage des variables,

En Python, ce n'est pas obligatoire, mais fortement recommandé.

Voici la syntaxe qu'il faut utiliser :

def nomFonction(argument: type) -> typeRetour:
		blocs des instructions
		return résultat
	

Exemple 1 : La fonction carré

  • Prend en paramètre un float
  • renvoie un float
Example: Typer les arguments et les résultats
Exemple : ici on précise dans la définition que le paramètre x est float et que la fonction renvoie aussi un float.

Exemple 2 : La fonction est_pair

  • Prend en paramètre un int
  • renvoie un bool
Example: Typer les arguments et les résultats
Exemple : ici on précise dans la définition que le paramètre x est int et que la fonction renvoie un booléen.

II Nommage

Une fonction :

  • Renvoie un résultat
  • ou fait quelques chose

Dans le deux cas, c'est une ACTION, et on nomme (le plus souvent) un fonction par un verbe. Ceci est particulièrement important pour les fonction qui font quelques chose sans renvoyer de résultat.

La convention PEP8 donne l'habitude de nommer les fonctions (comme les variables) avec des lettres minuscules et des tirets bas (celui du "8") _.


Exemples : lire_fichier, resoudre_equation, creer_grille_vide etc...

Comme pour les noms de variables, il est absolument recommandé de ne pas utiliser de caractères accentués dans les noms des fonctions.


On préfère toutefois parfois (ou souvent suivant les personnes) la convention dite camelCase qui consiste a écrire en minuscules, mais si le nom est constitué de plusieurs mots, on met une majuscules à tous les mots sauf le premier. Exemples : lireFichier, resoudreEquation, creerGrilleVide etc...

Pour clarifier la fonction, il est conseillé d'utiliser un verbe dans son nom (obtenir, donner, get, set, ...).

III. La docstring

Il est important de documenter vos fonctions, c'est-à-dire de décrire en quelques phrases le rôle de la fonction, de donner des informations sur la fonction, le lien entre les entrées et la sortie.

Pour cela, juste en dessous de la première ligne définissant la fonction, il suffit de mettre ses informations :

"""
Entrées : <donner la nom des paramètres, leur rôle et leurs types>
Sortie : préciser ce que renvoie la fonction (en précisant le type) ou péciser qu'elle ne renvoie rien, et décrire e qu'elle fait
"""
C'est ce que l'on appelle (en bon franglais) la docstring de la fonction.

Exemple 1

Example: Exemple 1 : la docstring de la fonction carre()
Documenter une fonction, accéder à la documentation

Exemple 2

Example: Exemple 2 : la docstring de la fonction puissance(x,n)
Documenter une fonction, accéder à la documentation

Exemple 3

Example: Exemple 3 : la docstring de la fonction min_et_max(lst)
Documenter une fonction, accéder à la documentation

L'intérêt de l'auto-documentation d'une fonction par un texte est double :

  • Pour vous : le faire vous oblige à réfléchir au contenu de votre fonction avant de la programmer ; c'est un gain d'efficacité,
  • Pour les utilisateurs de votre code (ou pour vous longtemps après avoir programmé la fonction) : Quand on saisit dans la console, après l'exécution de la fonction, l'instruction help(nom de la fonction), Python affiche le docstring de la fonction ce qui nous permet d'avoir des informations sur la fonction en cas d'oubli.

Exercices

Exercice 1
Coding Exercise: documenter une fonction mystère
Ecrire une docstring et les signatures.

La formulation qui est programmée dans la correction est un exemple, la votre peut être rédigée un peu différement mais elle doit contenir les mêmes informations.
Exercice 2
Coding Exercise: documenter une fonction mystère
Ecrire une docstring et les signatures.

La formulation qui est programmée dans la correction est un exemple, la votre peut être rédigée un peu différement mais elle doit contenir les mêmes informations.