Rappel sur les docstrings en Python

Nous faisons une petite pause dans l'évolution de notre programme pour parler des 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 !

Que cela soit un rappel ou non, voici le fonctionnement 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 ce que retourne une fonction ou une méthode. Regardons donc un exemple pour la fonction combat :

def combat(p1, p2):
	"""Effectue un combat entre deux personnages et renvoie le nom du vainqueur."""
…

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().

4) Ajoutez la docstring à votre fonction combat() et vérifiez qu'elle apparait lorsque vous appelez help(combat).

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.