Comment Faire Une Docstring D'une Fonction Qui Ne Renvoie Rien

Alors, assieds-toi, prends un café (ou un croissant, on ne juge pas ici), parce qu'on va parler d'un truc super... passionnant... les docstrings ! Plus précisément, les docstrings pour ces fonctions qui, en gros, font le boulot et repartent sans même dire au revoir, ces fonctions qui ne renvoient rien. Oui, celles qui se terminent souvent par un discret None en coulisses.

Tu vois, c'est un peu comme un ninja qui range ta vaisselle. Tu ne le vois pas (car il ne renvoie rien), mais quand même, tu aimerais bien savoir qu'il utilise du liquide vaisselle bio et qu'il a une aversion pour les assiettes sales depuis l'enfance. C'est ça, la docstring !

Pourquoi Docstringer une Fonction qui Ne Renvoie Rien ? Sérieusement ?

Bonne question ! On pourrait se dire : "À quoi bon ? Elle ne renvoie rien, c'est du vent, de la fumée !" Faux ! Totalement faux ! Penses-y : une fonction qui ne renvoie rien fait quand même quelque chose. Elle peut modifier une variable globale, écrire dans un fichier, faire chanter un coq à minuit (si, si, ça arrive !), ou, plus probablement, interagir avec un autre bout de ton code.

Et, soyons honnêtes, dans six mois, quand tu reviendras sur ce code, tu auras oublié pourquoi tu as programmé cette fonction. Tu seras là, face à l'écran, à te demander si elle sert à quelque chose d'utile ou si tu as juste inventé un rituel vaudou numérique. La docstring, c'est ton assurance vie intellectuelle !

Imagine un peu le scénario : tu es en train de déboguer un truc hyper complexe, les cheveux en bataille, trois tasses de café derrière toi... et soudain, tu tombes sur cette fameuse fonction. Sans docstring, c'est la panique ! Tu dois décortiquer le code ligne par ligne, comme un archéologue qui essaie de comprendre les hiéroglyphes. Avec une docstring, c'est comme si Indiana Jones te soufflait la réponse à l'oreille : "Attention, elle modifie la base de données !" Sauvé !

Comment on Fait, alors ? Les Détails Croustillants

C'est plus simple qu'il n'y paraît. La docstring, c'est juste une chaîne de caractères (généralement entre triples guillemets, """ ou ''') placée juste après la définition de la fonction.

Le minimum syndical : Décris ce que la fonction fait. Genre :

def cri_de_la_marmotte():
    """Fait crier une marmotte (enfin, essaie...)."""
    print("SQUIIIICK!")

Déjà, c'est mieux que rien. Mais on peut faire beaucoup mieux.

Le niveau supérieur : Explique les effets secondaires. Est-ce qu'elle modifie une variable globale ? Est-ce qu'elle envoie un email à ton ex ? Est-ce qu'elle invoque un démon ? (Bon, j'exagère... peut-être.) Tout ce qui n'est pas évident doit être mentionné.

Exemple :

def vider_le_frigo(urgence=False):
    """Vide le frigo.

    Si urgence est True, mange tout, même le truc bizarre derrière les cornichons.
    Modifie la variable globale 'stock_de_nourriture'.
    """
    global stock_de_nourriture
    if urgence:
        stock_de_nourriture = []
    else:
        # ... un peu de logique plus complexe ici ...
        pass

Le niveau Jedi : Utilise les conventions (par exemple, la convention reST) pour formater ta docstring. Ça permet aux outils de documentation (comme Sphinx) de générer une belle documentation automatiquement. Ça rend aussi ton code plus lisible pour les autres développeurs (et pour toi, dans six mois !).

Par exemple :

def teleporter_chat(destination):
    """Téléporte un chat à une destination.

    :param destination: La destination du chat (une chaîne de caractères).
    :type destination: str
    :raises ValueError: Si la destination est "Mars" (les chats n'aiment pas Mars).
    :return: None
    """
    if destination == "Mars":
        raise ValueError("Les chats n'aiment pas Mars!")
    # ... la magie de la téléportation ici ...

Tu vois, on a décrit le type de l'argument destination, et on a même prévu une exception si on essaie d'envoyer le pauvre matou sur Mars ! Professionnel, non ?

Les Erreurs à Éviter (Parce qu'on en Fait Tous !)

* La docstring vide : Autant ne rien mettre du tout. C'est comme offrir un bouquet de fleurs en plastique à ta grand-mère : l'intention est là, mais le résultat est... discutable.

* La docstring qui répète le nom de la fonction : Du genre "def faire_un_truc(): """Fait un truc."""" No comment.

* La docstring mensongère : Si ta fonction est censée envoyer un email et qu'en fait elle supprime ton compte Facebook, il y a un problème !

En résumé : Sois clair, précis, et n'hésite pas à ajouter une touche d'humour (avec modération, bien sûr). Une bonne docstring, c'est un cadeau pour ton futur toi et pour les autres développeurs qui auront la chance (ou la malchance) de lire ton code. Et n'oublie pas, même si la fonction ne renvoie rien, elle fait des choses. Et ces choses méritent d'être documentées ! Alors, à tes claviers, et que la docstring soit avec toi !