Commenter le Code

Les commentaires dans le code source remplissent plusieurs rôles cruciaux :

• Explication du Code : Les commentaires expliquent le but, la logique et le fonctionnement du code, ce qui facilite la compréhension, même pour d'autres développeurs. C'est les commentaires que vous devez travailler à rendre obsolète en codant proprement.

• Débogage : Les commentaires peuvent servir à signaler des problèmes potentiels, à indiquer des zones de code à examiner plus attentivement, ou à expliquer pourquoi un choix particulier a été fait. C'est la seule chose que j'utilise encore, pour ne pas oublier quelque chose quand je développe, quand je prend des notes pour le moi de plus tard, mais donc, ce commentaire est voué à disparaître quand mon code est fini.

• Documentation : Les commentaires documentent l'utilisation des fonctions, des variables, des paramètres, des retours, et des bibliothèques, facilitant ainsi l'utilisation de ces éléments par d'autres développeurs. Vous me verrez peut-être utiliser ce genre de code pour vous aider à comprendre ce que je fais régulièrement dans le code

Lorsque vous commentez votre code, suivez ces bonnes pratiques :

• Commentaires Clairs : Utilisez des commentaires clairs et concis. Évitez d'écrire des commentaires superflus ou confus.

• Majuscules et Ponctuation : Commencez les commentaires par une majuscule et terminez-les par un point. Utilisez une grammaire correcte. Si c'est pour écrire de manière codée, à quoi bon commenter...

• Évitez les Commentaires Évidents : Inutile de commenter chaque ligne de code. Les commentaires doivent apporter de la valeur en expliquant des concepts ou des décisions non évidents.

• Mises à Jour : Mettez à jour vos commentaires en même temps que le code. Des commentaires obsolètes ou incorrects peuvent être trompeurs. Ce qui donne encore un point en plus pour ma méthode, car un mauvais commentaire est plus destructeur qu'un mauvais code pour le développement en équipe.

La documentation des fonctions est particulièrement importante. Les commentaires des fonctions devraient expliquer : Attention qu'on ne parle pas de simple commentaires, mais bien de commentaires de documentation, qui permettent, dans la plupart des IDE d'afficher des informations au survol de la fonction

• Description : Le but de la fonction, ce qu'elle fait.

• Paramètres : Les entrées de la fonction, leur signification et leurs types.

• Valeurs de Retour : La valeur renvoyée par la fonction et son type.

• Exemples : Des exemples d'utilisation de la fonction.

Dans de nombreux langages de programmation, vous pouvez utiliser des docstrings pour documenter les fonctions. Les docstrings sont des chaînes de caractères placées au début d'une fonction et peuvent être extraites automatiquement pour générer de la documentation.

Exemple en Python :

def addition(a, b):
    """
    Cette fonction effectue une addition.
    
    :param a: Le premier nombre à additionner.
    :param b: Le deuxième nombre à additionner.
    :return: Le résultat de l'addition.
    """
    return a + b
Copy

Exemple en Java avec Javadoc:

/**
 * Cette fonction effectue une addition.
 * 
 * @param a Le premier nombre à additionner.
 * @param b Le deuxième nombre à additionner.
 * @return Le résultat de l'addition.
 */
public int addition(int a, int b) {
    return a + b;
}
Copy

Exemple en PHP avec PHPDocumentor :

/**
 * Cette fonction effectue une addition.
 * 
 * @param int $a Le premier nombre à additionner.
 * @param int $b Le deuxième nombre à additionner.
 * @return int Le résultat de l'addition.
 */
function addition($a, $b) {
    return $a + $b;
}
Copy

Il existe des outils de génération de documentation, tels que Doxygen, Javadoc, Sphinx, et d'autres, qui peuvent extraire des commentaires de code pour générer automatiquement des documents lisibles par les humains.

Ces outils facilitent la création et la maintenance de la documentation, ce qui est particulièrement utile pour les projets complexes.

Lors de la révision du code, assurez-vous que les commentaires sont précis, à jour, et utiles. Les commentaires obsolètes ou incorrects peuvent être plus nuisibles que l'absence de commentaires.

La documentation et les commentaires sont une composante essentielle de la qualité du code, et les développeurs devraient les considérer comme une partie intégrante du processus de développement, surtout en équipe, et surtout dans les codes soit trop complexe, soit mal exprimés.

#cours #blindcode #algo #cours #code #blindcode

créé le 2023-10-16 à 13:43