Documenter son code⚓︎
Utilisation des commentaires⚓︎
À priori, il sera plus simple de s'y retrouver dans un code commenté. Parfois cependant, un code bien écrit, tel que celui de la fonction perimetre vue précédemment suffit et rend l'utilisation de ces commentaires inutiles.
Il faut aussi éviter les commentaires qui n'apporte rien :
# un commentaire inutile
x = x - 1 # diminuer x
# un commentaire peut-être utile
x = x - 1 # pour éviter un dépassement d'indice de liste
Documentation d'une fonction (docstring)⚓︎
Dans la console Python ci-dessous, tapez help(print) :
qui renvoie une chaîne de caractère documentant l'utilisation de la fonction print.
La fonction help renvoie donc la documentation d'une fonction.
Il est possible de créer une telle documentation pour vos fonctions en utilisant les docstrings :
def multiplierpy-undchaine(chn, nb):bksl-nl """bksl-nl Renvoie une chaîne de caractères chn dupliquée nb foisbksl-nl :param str chn: la chaîne à dupliquerbksl-nl :param int nb: nombre de fois que chn doit être dupliquéebksl-nl :return: la chaîne dupliquéebksl-nl :rtype: strbksl-nl """bksl-nl return nb py-str chnbksl-nl
A
Z
exécutez le code ci-dessus puis tapez help(multiplier_chaine) dans cette console :
Remarques
Bien sûr, la fonction ci-dessus ne nécessite pas de docstring car elle est trop courte et déjà bien écrite, il ne s'agît que d'un exemple.
Par ailleurs la syntaxe utilisée (:param str chn: etc.) est une pure convention, vous n'êtes pas obligé de la respecter.
Exercice 2
- Testez la fonction suivante jusqu'à comprendre ce qu'elle fait :
def fonc(a):bksl-nl b = 0bksl-nl for c in a:bksl-nl if c not in "aeiouy":bksl-nl b = b + 1bksl-nlbksl-nl return bbksl-nlbksl-nl###
- Renommez la fonction et les variables utilisées pour augmenter sa lisibilité.
- Écrivez une docstring pour cette fonction.
PEP257
La PEP257 spécifie les docstrings.