Docstrings

Les docstrings sont la documentation de votre programme. Ils ne changent absolument pas le fonctionnement du programme mais permettent aux utilisateurs et développeurs de votre programme de mieux le comprendre.

La documentation est souvent négligée par les développeurs car on veut souvent aller vite et nous avons l'impression que cela ne sert à rien. Erreur ! La documentation permet d'éviter de nombreux bugs car le code est plus compréhensible. De plus, il est fort probable que ça soit vous qui essairez de comprendre ce code dans plusieurs semaines ou mois. La documentation vous permettera de gagner beaucoup de temps.

En effet, lorsqu'on écrit un programme tout est frais et logique dans notre tête, mais plusieurs mois après, il peut être difficle de comprendre notre propre code sans explications. Pour une personne extérieure cela peut même être impossible. Voilà pourquoi il est indispensable de documenter son code avec des commentaires et des docstrings !

Qu'est-ce qu'une docstring ?

Une docstring est une chaîne de caractères avec trois doubles quotes """ situées au début d'un module, d'une fonction, d'une classe (on verra cela plus tard) ou d'une méthode (on verra aussi cela plus tard). Elle explique ce que fait le code et donne éventuellement ce que retourne une fonction ou une méthode. Nous utiliserons principalement les docstrings pour les fonctions. Regardons par exemple une fonction qui renvoie le plus grand élément d'un tableau :

def maxtab(tab):
	"""Renvoie le plus grand élément du tableau tab."""
	max = tab[0]
    for k in tab:
        if k > max:
            max = k
    return max

Cette chaîne de caractères sera ignorée lors de l'éxécution du programme. Par contre elle sera utilisée lorsqu'on demande de l'aide sur une fonction avec help().

>>> help(maxtab)
Help on function maxtab in module __main__:

maxtab(tab)
    Renvoie le plus grand élément du tableau tab.

L'intéret principal des docstring est d'avoir une façon universelle de documenter le code. Cela permettra donc un une personne lisant le code de comprendre rapidement son utilité.

Docstrings sur plusieurs lignes

Il est possible d'écrire des docstrings sur plusieurs lignes. Il faudra alors commencer par un résumé sur une ligne puis, après une ligne vièrge, donner les détails.

def maFonction():
	"""
	Résumé de ce que fait cette fonction.

	Une explication détaillée.
	Encore une explication détaillée.
	"""
	…

Sources et compléments

Docstrings conventions

la page officelle de Python sur les docstrings

Les docstrings en Python

un article de blog en français qui explique les docstrings de manière simple et détendue.