Documenter et commenter le code

En bref

Résumé de l’article

Dans cet article, nous fournissons des détails sur la documentation du code et le rôle qu’elle joue dans le développement logiciel, surtout lors de l’écriture de codes destinés à être publiés.

Points importants à retenir

• La documentation et les tests ensemble assurent la robustesse et la durabilité à long terme du logiciel.

• Documenter le code le rend plus facile à lire et maintenir, facilitant le travail d’équipe et le partage des connaissances.

• Les nouveaux développeurs peuvent se mettre à niveau plus rapidement avec du code bien documenté.

• Une bonne documentation aide au débogage en expliquant la logique du code et soutient des tests approfondis en décrivant les comportements attendus et les cas limites.

Contenu de l’article

1 — Que signifie documenter un code ?

1.1 — Pourquoi documenter ?

La documentation du code joue un rôle crucial pour rendre le projet lisible et compréhensible pour tous les développeurs. Elle inclut des commentaires dans le code, des guides d’utilisation, et des descriptions détaillées des fonctions et classes.

Une documentation bien écrite permet aux autres développeurs, ou même pour vous dans le futur, de rapidement saisir la fonctionnalité et l’architecture du logiciel, réduisant le temps nécessaire pour se familiariser avec le projet. De plus, une documentation complète favorise une meilleure collaboration entre les membres de l’équipe, car elle fournit une compréhension partagée de la base de code et de son comportement prévu. Ceci est particulièrement précieux dans les grandes équipes ou équipes distribuées où une communication claire est essentielle.

De plus, elle aide au débogage et aux tests en décrivant clairement les entrées attendues, les sorties, et les cas limites, minimisant ainsi les erreurs et améliorant la qualité globale du logiciel. En résumé, une documentation approfondie est un investissement qui rapporte en améliorant l’efficacité, la collaboration, et la qualité du code dans tout projet de développement.

Le code documenté est crucial pour plusieurs raisons. Premièrement, il améliore la lisibilité et la maintenabilité du logiciel. Quand le code est bien documenté, les autres développeurs peuvent facilement comprendre son but, sa structure, et sa fonctionnalité sans avoir à déchiffrer la logique par eux-mêmes. Ceci est particulièrement important dans un contexte d’équipe ou pour de nouveaux développeurs rejoignant un projet, car cela réduit significativement le temps d’intégration. De plus, la documentation fournit un contexte précieux sur pourquoi certaines décisions ont été prises, ce qui est essentiel pour la maintenance et la refactorisation futures. Sans documentation appropriée, le risque d’introduire des erreurs lors de mises à jour ou modifications augmente, car l’intention derrière le code original peut être mal comprise.

Elle agit comme un guide de référence, détaillant l’utilisation des fonctions, classes, et modules, ce qui aide à assurer la cohérence et la justesse tout au long du processus de développement. Une bonne documentation soutient également une meilleure collaboration, car les membres de l’équipe peuvent s’appuyer sur le code documenté pour comprendre comment les différentes parties du système interagissent. De plus, elle facilite l’intégration de nouvelles fonctionnalités et le débogage, car les développeurs peuvent suivre la logique documentée pour identifier les problèmes potentiels plus efficacement.

Un code bien documenté est essentiel pour maintenir des pratiques de développement logiciel de haute qualité, évolutives et collaboratives.

1.2 — Différents types de documentation

Voici quelques types courants de documentation dans le développement logiciel :

• Documentation du code – Ce type de documentation est intégré directement dans le code source et inclut des commentaires, annotations, et docstrings. Elle explique le but, la fonctionnalité, et l’utilisation d’éléments de code individuels tels que les fonctions, classes, et modules. La documentation du code aide les développeurs à comprendre et maintenir efficacement la base de code.

• Documentation technique – La documentation technique fournit des informations détaillées sur l’architecture, la conception, et l’implémentation du logiciel. Elle peut inclure des diagrammes d’architecture système, des diagrammes de flux de données, des diagrammes de classes, et d’autres spécifications techniques. La documentation technique s’adresse principalement aux développeurs, architectes, et parties prenantes techniques pour comprendre le fonctionnement interne du logiciel.

• Documentation utilisateur (documentation pour l’utilisateur final) – La documentation utilisateur vise à aider les utilisateurs à comprendre comment utiliser le logiciel efficacement. Elle inclut des manuels utilisateur, guides, tutoriels, et FAQ qui fournissent des instructions, conseils, et aide au dépannage. La documentation utilisateur aide les utilisateurs à apprendre comment interagir avec le logiciel et accomplir leurs tâches efficacement.

2 — Documentation du code

Ici, nous nous concentrons sur la documentation du code. Dans ce contexte, il y a deux types principaux de documentation utilisés pour expliquer différents aspects du code : les commentaires et la documentation des signatures de fonctions et classes.

2.1 — Commentaires

Les commentaires sont des annotations textuelles ajoutées directement au code source. Le but des commentaires est de rendre le code plus facile à comprendre, pas de le paraphraser. Ils expliquent comment il fonctionne, ses intentions, ou fournissent des informations supplémentaires sur des parties complexes ou non triviales du code. Ils peuvent être utilisés pour décrire des algorithmes, des décisions de conception, des limitations, des TODO, etc.

En Python, les commentaires commencent par le caractère #. Ce symbole indique que le reste de la ligne est un commentaire. Les commentaires peuvent être écrits sur plusieurs lignes.

def inverse_capitalization (word: str) -> str:

    # Fill a list char by char
    result = []
    for char in word: # Loop over the characters of the word <-- Not very useful comment
        result.append(char.lower() if char.isupper() else char.upper()) # In Python we can make if conditions like this
    
    # Recreate the string
    return ''.join(result)

2.2 — Documentation des signatures de fonctions et classes

Dans de nombreux langages de programmation, il est possible de fournir une documentation des signatures de fonctions et classes. Cette documentation décrit les paramètres d’entrée, les valeurs de retour, les exceptions levées, etc.

Cette information peut être extraite automatiquement pour générer une documentation externe.

Python supporte les chaînes de documentation, souvent appelées “docstrings”, qui commencent et finissent par """. Ce sont des commentaires multi-lignes inclus directement dans le code source. Les docstrings sont généralement placées juste après la déclaration d’une fonction, méthode ou classe. Elles peuvent être utilisées pour fournir une documentation intégrée directement dans le code.

Voici un exemple d’une fonction documentée :

def inverse_capitalization (word: str) -> str:
    """
        Inverts the capitalization of a word.
        For instance Hello should be transformed to hELLO.
        In:
            * word: The word to process.
        Out:
            * The word with inversed capitalization.
    """

    # Fill a list char by char
    result = []
    for char in word:
        result.append(char.lower() if char.isupper() else char.upper())
    
    # Recreate the string
    return ''.join(result)

Les commentaires de documentation sont le meilleur moyen de générer une documentation automatique à partir du code source. Ils créent une documentation externe détaillée pour les classes et méthodes, que les développeurs peuvent consulter lors de l’utilisation de ces composants.

Pour aller plus loin

Il semble que cette section soit vide !

Y a-t-il quelque chose que vous auriez aimé voir ici ? Faites-le nous savoir sur le serveur Discord ! Peut-être que nous pouvons l’ajouter rapidement. Sinon, cela nous aidera à améliorer le cours pour l’année prochaine !

Pour aller au-delà

• pydoc.

  Exploitez la documentation de votre code pour générer des documents partageables.

• Convention PEP8 sur les docstrings.

  La partie de la convention Python sur la documentation.