Python - Docstrings

Bonjour, aspirants programmeurs Python ! Aujourd'hui, nous allons plonger dans le merveilleux monde des docstrings. En tant que professeur de science informatique amical et sympa, je suis excité de vous guider à travers cet aspect essentiel de la programmation Python. Alors, prenez votre boisson préférée, mettez-vous à l'aise, et partons ensemble dans cette aventure d'apprentissage !

Docstrings en Python

Imaginez que vous écrivez un journal intime. Au début de chaque entrée, vous pourriez noter un bref résumé de ce qui s'est passé ce jour-là. Eh bien, les docstrings en Python sont un peu comme ça ! Ce sont des chaînes spéciales qui décrivent ce qu'une partie de code fait, rendant plus facile pour vous (et les autres) de comprendre votre code plus tard.

En Python, les docstrings sont encadrées par des guillemets triples (""" ou ''') et sont placées juste après la définition d'une fonction, d'une classe ou d'un module. Voyons un exemple simple :

def saluer(nom):
"""Cette fonction salue la personne passée en tant que paramètre"""
print(f"Bonjour, {nom} !")

Dans cet exemple, la ligne entre les guillemets triples est notre docstring. Elle explique brièvement ce que la fonction saluer fait.

Docstrings sur une seule ligne

Pour des fonctions ou des classes simples, une docstring sur une seule ligne peut être tout ce dont vous avez besoin. Voici un autre exemple :

def carre(n):
"""Renvoie le carré d'un nombre."""
return n ** 2

Cette docstring est courte et piquante, nous disant exactement ce que la fonction fait en une seule ligne.

Docstrings sur plusieurs lignes

Pour des fonctions ou des classes plus complexes, vous pourriez avoir besoin d'une docstring sur plusieurs lignes. Celles-ci incluent généralement une ligne de résumé, suivie d'une ligne blanche, puis des informations plus détaillées. Voyons un exemple :

def calculer_surface(longueur, largeur):
"""
Calcule la surface d'un rectangle.

Paramètres :
longueur (float) : La longueur du rectangle
largeur (float) : La largeur du rectangle

Retourne :
float : La surface du rectangle
"""
return longueur * largeur

Cette docstring sur plusieurs lignes fournit des informations plus détaillées sur les paramètres de la fonction et ce qu'elle renvoie.

Docstrings pour les modules

Les modules peuvent également avoir des docstrings. Ceux-ci sont placés au tout début du fichier. Par exemple :

"""
Ce module contient des fonctions utilitaires pour les calculs géométriques.
Il inclut des fonctions pour calculer les surfaces et les volumes de diverses formes.
"""

def calculer_surface_cercle(rayon):
# Implémentation de la fonction ici

Docstrings pour les classes

Les classes peuvent également avoir des docstrings. Ceux-ci sont placés juste après la définition de la classe :

class Rectangle:
"""
Une classe pour représenter un rectangle.

Attributs :
longueur (float) : La longueur du rectangle
largeur (float) : La largeur du rectangle
"""

def __init__(self, longueur, largeur):
self.longueur = longueur
self.largeur = largeur

Accès aux Docstrings

L'un des aspects cool des docstrings est que vous pouvez y accéder programmatiquement. Python stocke la docstring comme l'attribut __doc__ de la fonction, de la classe ou du module. Voici comment vous pouvez y accéder :

def saluer(nom):
"""Cette fonction salue la personne passée en tant que paramètre"""
print(f"Bonjour, {nom} !")

print(saluer.__doc__)

Cela donnera en sortie : Cette fonction salue la personne passée en tant que paramètre

Meilleures pratiques pour écrire des Docstrings

Maintenant que nous savons comment écrire des docstrings, parlons de quelques meilleures pratiques :

1. Soyez concis mais informatif
2. Utilisez une grammaire et une ponctuation correctes
3. Soyez cohérent dans votre style
4. Incluez des informations sur les paramètres et les valeurs de retour pour les fonctions
5. Pour les classes, décrivez les attributs et les méthodes importants

Style de Docstring de Google

Google a son propre guide de style pour les docstrings. Voici un exemple :

def diviser(a, b):
"""Divise deux nombres.

Args:
a (int) : Le numérateur.
b (int) : Le dénominateur.

Returns:
float : Le résultat de la division.

Raises:
ZeroDivisionError : Si b est 0.
"""
if b == 0:
raise ZeroDivisionError("Impossible de diviser par zéro")
return a / b

Style de Docstring NumPy/SciPy

Si vous travaillez avec des bibliothèques Python scientifiques, vous pourriez rencontrer le style NumPy/SciPy :

def calculer_moyenne(nombres):
"""
Calcule la moyenne arithmétique d'une liste de nombres.

Paramètres
----------
nombres : list
Une liste de nombres.

Retours
-------
float
La moyenne arithmétique de la liste d'entrée.
"""
return sum(nombres) / len(nombres)

Style de Docstring Sphinx

Sphinx est un générateur de documentation populaire pour Python. Son style est similaire au format reStructuredText :

def fibonacci(n):
"""
Génère une séquence de Fibonacci jusqu'à n.

:param n: Le nombre de nombres de Fibonacci à générer
:type n: int
:return: Une liste de nombres de Fibonacci
:rtype: list
"""
sequence = [0, 1]
while len(sequence) < n:
sequence.append(sequence[-1] + sequence[-2])
return sequence[:n]

Docstring vs Commentaire

Vous vous demandez peut-être, "Quelle est la différence entre une docstring et un commentaire ordinaire ?" Bonne question ! Analysons cela :

1. Syntaxe : Les docstrings utilisent des guillemets triples, tandis que les commentaires utilisent #.
2. Placement : Les docstrings viennent juste après une définition, tandis que les commentaires peuvent aller n'importe où.
3. Objectif : Les docstrings expliquent ce que le code fait, les commentaires expliquent comment il le fait.
4. Accessibilité : Les docstrings peuvent être accessibles programmatiquement, les commentaires non.

Voici un exemple rapide pour illustrer :

def ajouter(a, b):
"""
Ajoute deux nombres et renvoie le résultat.
"""
# C'est un commentaire expliquant comment nous faisons l'addition
return a + b  # C'est un commentaire en ligne

Et voilà, les amis ! Nous avons couvert les ins et outs des docstrings Python. Souvenez-vous, une bonne documentation est comme laisser une piste de pain pour le futur vous (ou d'autres développeurs) à suivre. Cela peut sembler du travail supplémentaire maintenant, mais croyez-moi, vous vous en remercirez plus tard !

Voici un tableau de référence rapide des styles de docstring que nous avons couverts :

Style	Résumé	Exemple
Single-Line	Brève description sur une ligne	"""Renvoie le carré d'un nombre."""
Multi-Line	Description détaillée avec paramètres et valeur de retour	"""Calcule la surface d'un rectangle.\n\nParamètres :\n..."""
Google	Inclut les sections Args, Returns et Raises	"""Divise deux nombres.\n\nArgs:\n..."""
NumPy/SciPy	Utilise les sections Parameters et Returns avec un formatage plus détaillé	"""Calcule la moyenne arithmétique d'une liste de nombres.\n\nParameters\n----------\n..."""
Sphinx	Utilise les champs :param:, :type:, :return: et :rtype:	"""Génère une séquence de Fibonacci jusqu'à n.\n\n:param n: ..."""

Bon codage, et que vos docstrings soient toujours claires et informatives !

Credits: Image by storyset