Commentaires et documentation | NSI 1ère

Types de commentaires

Commentaires = Explication du code

Pour faciliter la compréhension du code

Commentaires simples :

Ligne unique avec #
Explication courte
# Calcul du carré d'un nombre

Docstrings :

Triple guillemet"""
Documentation de fonctions
Utilisation, paramètres, retour

Syntaxe des commentaires

Python, Shell : # commentaire

://

Java, C++ : // commentaire

/* */

Java, C++ : /* commentaire */

Exemples de documentation

# Fonction pour calculer la moyenne
def calculer_moyenne(notes):
    """
    Calcule la moyenne d'une liste de notes.
    
    Args:
        notes (list): Liste de nombres positifs
        
    Returns:
        float: Moyenne des notes
    """
    somme = sum(notes)
    nb_notes = len(notes)
    return somme / nb_notes if nb_notes > 0 else 0

# Exemple d'utilisation
resultat = calculer_moyenne([15, 18, 12])

🎯

But : expliquer l'objectif du code

🔍

Explication : détailler le fonctionnement

📋

Documentation : décrire les paramètres

⚠️

Limites : préciser les contraintes

Bonnes pratiques

📝

Commenter les parties complexes

📏

Longueur raisonnable des lignes

🔄

Mettre à jour avec le code

🧠

Expliquer le pourquoi, pas le quoi

Importance de la documentation

👥

Collaboration : autres développeurs

🔄

Maintenance : comprendre le code ancien

📚

Formation : apprentissage du code

🔍

Débogage : identifier les erreurs

📈

Qualité : code professionnel

Erreurs Fréquentes

Erreur 1 :

Oublier de commenter les fonctions importantes

Erreur 2 :

Commentaires obsolètes non mis à jour

Erreur 3 :

Trop de commentaires évidents

Erreur 4 :

Documentation incomplète des paramètres

Formats de documentation

Inline :

# Commentaire sur la même ligne
variable = valeur # Description

Bloc :

"""Documentation multi-lignes"""
Pour fonctions, classes, modules

Fichier externe :

README.md, docs/, wiki
Documentation complète du projet