Sommaire

Documenter le code Documenter le code

Il existe un ensemble de recommandations pour Python qui sont formulées dans les documents PEP. La recommandation PEP 257 donne un ensemble de conseils pour documenter et commenter le code.

D’une manière générale, le code doit être commenté pour chaque fonction. PEP recommande également de ne pas commenter de façon excessive. En effet, les commentaires du type :

# ceci est un commentaire

ne doivent être utilisés que pour signaler à un relecteur du code ou rappeler à son créateur une particularité qui ne serait pas explicite à la lecture du code en question (le commentaire est à placer, à proximité du passage commenté).

Le code doit comporter en particulier des lignes de documentation pour toutes les fonctions. Ces blocs de documentation sont délimités à l’aide de guillemets :

        """Ceci est un bloc de commentaire"""

Il est possible d’insérer des commentaires sur une ou plusieurs lignes.

D’une manière générale, un commentaire comporte toujours en première ligne la description du rôle de la fonction. Le PEP 257 précise explicitement que cette ligne ne doit pas être un copier-coller du prototype de la fonction. Les lignes ci-après illustrent la documentation d’une méthode qui ne retourne pas de paramètre et ne prend ...