Commentaires utiles - Documentation et communication | Numérique et Sciences Informatiques

Types de commentaires

\( \text{Commentaire} = \{\text{Explication}, \text{Documentation}, \text{Clarification}\} \)

Fonctions principales

Exemple Python :

# Calcul du PGCD avec Euclide
def pgcd(a, b):
"""Retourne le PGCD de a et b"""

Règles pour commentaires

✅

Clarté et précision

📝

Courts et pertinents

🎯

Expliquer le pourquoi

❌

Ne pas répéter le code

Formats de commentaires

💬

Ligne unique (#)

📄

Bloc triple guillemets

📍

En-tête de fonction

⚠️

Notes importantes

Bonnes pratiques

Exemples corrects :

# Bon exemple
def tri_bulle(tableau):
    """Trie le tableau en utilisant l'algorithme du tri à bulle"""
    n = len(tableau)
    for i in range(n):
        for j in range(0, n-i-1):
            if tableau[j] > tableau[j+1]:
                tableau[j], tableau[j+1] = tableau[j+1], tableau[j]
    return tableau

Exemples à éviter :

# Mauvais exemple
def tri_bulle(tableau):
    # On parcourt le tableau
    n = len(tableau)
    for i in range(n):
        # On compare les éléments adjacents
        for j in range(0, n-i-1):
            # Si le premier est plus grand que le second
            if tableau[j] > tableau[j+1]:
                # On échange les positions
                tableau[j], tableau[j+1] = tableau[j+1], tableau[j]
    return tableau

Éléments à commenter

Fonctions :

Description, paramètres, retour

Algorithmes complexes :

Explication des étapes principales

Choix techniques :

Pourquoi cette solution plutôt qu'une autre

Modèles de commentaires

Docstring Python

def recherche_dichotomique(tableau, element):
    """
    Recherche un élément dans un tableau trié
    
    Args:
        tableau (list): Le tableau trié à rechercher
        element: L'élément à trouver
    
    Returns:
        int: Indice de l'élément ou -1 si absent
    """
    debut, fin = 0, len(tableau) - 1
    while debut <= fin:
        milieu = (debut + fin) // 2
        if tableau[milieu] == element:
            return milieu
        elif tableau[milieu] < element:
            debut = milieu + 1
        else:
            fin = milieu - 1
    return -1

Commentaires stratégiques

def tri_fusion(tableau):
    # Cas de base : tableau de taille 1 ou 0
    if len(tableau) <= 1:
        return tableau
    
    # Diviser le tableau en deux parties
    milieu = len(tableau) // 2
    gauche = tri_fusion(tableau[:milieu])
    droite = tri_fusion(tableau[milieu:])
    
    # Fusionner les parties triées
    # Algorithme de fusion : O(n)
    resultat = []
    i = j = 0
    while i < len(gauche) and j < len(droite):
        if gauche[i] <= droite[j]:
            resultat.append(gauche[i])
            i += 1
        else:
            resultat.append(droite[j])
            j += 1
    
    # Ajouter les éléments restants
    resultat.extend(gauche[i:])
    resultat.extend(droite[j:])
    return resultat

Conseils pour bien commenter

🎯

Commenter l'intention, pas l'évidence

📝

Maintenir la cohérence du style

🔄

Mettre à jour les commentaires avec le code

👥

Penser aux autres développeurs