Documenting and commenting the 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, en particulier 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 facilite sa lecture et sa maintenance, favorisant le travail en équipe et le partage des connaissances.

• Les nouveaux développeurs peuvent monter en compétence plus rapidement avec un 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 rédigée permet à d’autres développeurs, ou même à votre futur vous, de saisir rapidement la fonctionnalité et l’architecture du logiciel, réduisant ainsi 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 attendu.
Cela est particulièrement précieux dans les équipes nombreuses ou distribuées où une communication claire est essentielle.

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

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

Elle sert de 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 se fier au code documenté pour comprendre comment 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 plus efficacement les problèmes potentiels.

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 documentations

Voici quelques types courants de documentation en 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.
  Il explique le but, la fonctionnalité et l’utilisation des é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 est principalement destinée 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 efficacement le logiciel.
  Elle inclut des manuels utilisateur, guides, tutoriels et FAQ qui fournissent des instructions, astuces et conseils de 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 existe deux principaux types 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 # (// en Java).
Ce symbole indique que le reste de la ligne est un commentaire.
Les commentaires peuvent être écrits sur plusieurs lignes (en Java, un commentaire multi-lignes peut être entouré par /* et */).

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)

public String inverseCapitalization(String word){
    // Fill an array char by char
    char[] result = new char[word.length()];
    for (int i = 0; i < word.length(); i++) {
        char c = word.charAt(i);
        result[i] = Character.isUpperCase(c) ? Character.toLowerCase(c) : Character.toUpperCase(c); // In Java we can make if conditions like this
    }

    // Recreate the string
    return new String(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 des fonctions et classes.
Cette documentation décrit les paramètres d’entrée, les valeurs de retour, les exceptions levées, etc.

Ces informations peuvent être extraites automatiquement pour générer une documentation externe.

Python supporte les chaînes de documentation, souvent appelées “docstrings”, qui commencent et se terminent 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.

En Java, ces commentaires commencent par /** et se terminent par */ et
sont généralement placés juste avant la déclaration d’une fonction, méthode ou classe.

Voici un exemple de 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)

/**
 * Inverts the capitalization of a word.
 * For instance Hello should be transformed to hELLO.
 *
 * @param word The word to process.
 * @return     The word with inversed capitalization.
 */
public String inverseCapitalization(String word){
    // Fill an array char by char
    char[] result = new char[word.length()];
    for (int i = 0; i < word.length(); i++) {
        char c = word.charAt(i);
        result[i] = Character.isUpperCase(c) ? Character.toLowerCase(c) : Character.toUpperCase(c); // In Java we can make if conditions like this
    }

    // Recreate the string
    return new String(result);
}

Les commentaires de documentation sont la meilleure façon de générer automatiquement une documentation à 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

On dirait que cette section est vide !

Y a-t-il quelque chose que vous auriez aimé voir ici ?
Faites-le nous savoir sur le serveur Discord !
Peut-être pouvons-nous 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 concernant la documentation.