Concepts & Exercices
Qualité_{commentaire} = \frac{Clarté + Pertinence + Concision}{3}
Calcul de la qualité d'un commentaire
Commentaire de fonction
🎯
Décrire ce que fait la fonction
Commentaire de variable
:variables
Expliquer le rôle de la variable
Commentaire d'algorithme
🧩
Expliquer la logique du code
Commentaire de bloc
📦
Décrire un ensemble d'instructions
Caractéristiques :
- Clarté : Langage simple et compréhensible
- Pertinence : Information utile et directement liée au code
- Concision : Bref mais complet
- Actualité : Mis à jour avec les modifications du code
Exercice 1
Commentaires de fonction et de paramètres
Exercice 2
Commentaires de variables et de constantes
Exercice 3
Commentaires d'algorithme complexe
Exercice 4
Commentaires de bloc de code
Exercice 5
Documentation de module complet
Corrigé : Exercices 1 à 3
1 Commentaires de fonction
Définition :
Problème : Ajouter des commentaires utiles à une fonction
Bonnes pratiques :
- Commenter l'objectif de la fonction
- Spécifier les paramètres et leur rôle
- Indiquer la valeur de retour
- Expliquer les cas particuliers
1
Identifier la fonction
2
Décrire son objectif
3
Documenter les paramètres
4
Préciser la valeur de retour
Étape 1 : Code sans commentaires
FONCTION CalculerTauxCroissance(population_initiale, population_finale, annees) : Réel
taux ← ((population_finale - population_initiale) / population_initiale) * 100
taux_annuel ← taux / annees
RETOURNER taux_annuel
FINÉtape 2 : Code avec commentaires utiles
/**
* Calcule le taux de croissance annuel moyen d'une population
*
* @param population_initiale : Population au début de la période
* @param population_finale : Population à la fin de la période
* @param annees : Nombre d'années de la période
* @return Taux de croissance annuel en pourcentage
*/
FONCTION CalculerTauxCroissance(population_initiale, population_finale, annees) : Réel
// Calcul du taux de croissance total sur la période
taux ← ((population_finale - population_initiale) / population_initiale) * 100
// Calcul du taux annuel moyen en divisant par le nombre d'années
taux_annuel ← taux / annees
// Retourne le taux de croissance annuel en pourcentage
RETOURNER taux_annuel
FINÉtape 3 : Analyse des commentaires
Commentaire de documentation : Explique l'objectif de la fonction
Commentaire de paramètres : Précise le rôle de chaque paramètre
Commentaire de retour : Indique la signification de la valeur retournée
Commentaires internes : Expliquent les étapes de calcul
Fonction documentée avec commentaires utiles
Commentaires ajoutés :
Les commentaires expliquent clairement le rôle de la fonction, ses paramètres et sa valeur de retour.
Règles de commentaire de fonction :
• Expliquer l'objectif : Quelle est la finalité de la fonction ?
• Documenter les paramètres : Que représente chaque paramètre ?
• Indiquer la valeur de retour : Quel est le résultat produit ?
2 Commentaires de variables
Définition :
Problème : Documenter les variables avec des commentaires pertinents
1
Identifier les variables importantes
2
Déterminer leur rôle
3
Expliquer leur utilité
4
Documenter les constantes
Étape 1 : Code sans commentaires
constante PI ← 3.14159265359
constante TAILLE_MAX ← 1000
variable rayon ← 5
variable aire ← PI * rayon * rayon
variable perimetre ← 2 * PI * rayonÉtape 2 : Code avec commentaires utiles
// Constante mathématique pour les calculs géométriques
constante PI ← 3.14159265359
// Taille maximale autorisée pour les tableaux
constante TAILLE_MAX ← 1000
// Rayon du cercle en unités arbitraires
variable rayon ← 5
// Aire du cercle calculée selon la formule A = πr²
variable aire ← PI * rayon * rayon
// Périmètre du cercle calculé selon la formule P = 2πr
variable perimetre ← 2 * PI * rayonÉtape 3 : Analyse des commentaires
| Variable | Commentaire | Pertinence |
|---|---|---|
| PI | Constante mathématique | ✅ Utile |
| TAILLE_MAX | Limite de tableau | ✅ Utile |
| rayon | Rayon du cercle | ✅ Utile |
| aire | Formule de calcul | ✅ Utile |
| perimetre | Formule de calcul | ✅ Utile |
Variables documentées avec commentaires pertinents
Commentaires ajoutés :
Chaque variable est accompagnée d'un commentaire expliquant son rôle et son utilité.
Règles de commentaire de variables :
• Expliquer le rôle : À quoi sert la variable ?
• Indiquer l'unité : Si applicable (mètres, secondes, etc.)
• Justifier les constantes : Pourquoi cette valeur ?
3 Commentaires d'algorithme
Définition :
Problème : Commenter un algorithme complexe pour en expliquer la logique
Algorithme_{complexe} = \sum_{i=1}^{n} (Etape_i × Explication_i)
Lisibilité = \frac{Commentaires_{pertinents}}{Complexité_{algorithme}} × 100\%
Étape 1 : Algorithme de tri rapide sans commentaires
FONCTION TriRapide(tableau) : Tableau
SI LONGUEUR(tableau) ≤ 1 ALORS
RETOURNER tableau
FIN SI
pivot ← tableau[LONGUEUR(tableau) DIV 2]
gauche ← [x POUR x IN tableau SI x < pivot]
milieu ← [x POUR x IN tableau SI x = pivot]
droite ← [x POUR x IN tableau SI x > pivot]
RETOURNER TriRapide(gauche) + milieu + TriRapide(droite)
FINÉtape 2 : Algorithme avec commentaires détaillés
/**
* Algorithme de tri rapide (QuickSort)
* Tri récursif basé sur le principe "diviser pour régner"
* Complexité moyenne : O(n log n), pire cas : O(n²)
*/
FONCTION TriRapide(tableau) : Tableau
// Cas de base : tableau vide ou à un seul élément est déjà trié
SI LONGUEUR(tableau) ≤ 1 ALORS
RETOURNER tableau
FIN SI
// Sélection du pivot : élément médian du tableau
pivot ← tableau[LONGUEUR(tableau) DIV 2]
// Partitionnement : création de trois sous-tableaux
// gauche : éléments strictement inférieurs au pivot
gauche ← [x POUR x IN tableau SI x < pivot]
// milieu : éléments égaux au pivot
milieu ← [x POUR x IN tableau SI x = pivot]
// droite : éléments strictement supérieurs au pivot
droite ← [x POUR x IN tableau SI x > pivot]
// Appel récursif sur les parties gauche et droite
// Combinaison des résultats triés
RETOURNER TriRapide(gauche) + milieu + TriRapide(droite)
FINÉtape 3 : Analyse de la documentation
Commentaire global : Explique l'algorithme et sa complexité
Commentaire de cas de base : Clarifie la condition d'arrêt
Commentaires de partitionnement : Expliquent chaque étape
Commentaire de combinaison : Explique la logique finale
Algorithme complexe documenté avec commentaires explicatifs
Documentation complète :
L'algorithme est maintenant clair et compréhensible grâce aux commentaires détaillés.
Règles de commentaire d'algorithme :
• Expliquer la logique générale : Quel est le principe de l'algorithme ?
• Documenter les étapes complexes : Clarifier les parties difficiles
• Indiquer la complexité : Si connue et pertinente
Corrigé : Exercices 4 à 5
4 Commentaires de bloc de code
Définition :
Problème : Documenter un bloc de code complexe avec des commentaires de section
Initialisation
🔧
Préparation des variables
Traitement
⚙️
Calculs principaux
Validation
✅
Vérification des résultats
Sortie
📤
Retour des résultats
Étape 1 : Bloc de code sans commentaires
variable notes ← [12, 15, 8, 17, 14, 9, 16, 11, 13, 10]
variable somme ← 0
POUR note IN notes FAIRE
somme ← somme + note
FIN POUR
variable moyenne ← somme / LONGUEUR(notes)
variable ecart_type ← 0
POUR note IN notes FAIRE
ecart_type ← ecart_type + (note - moyenne) * (note - moyenne)
FIN POUR
ecart_type ← RACINE(ecart_type / LONGUEUR(notes))
variable mention ← ""
SI moyenne >= 16 ALORS mention ← "Très bien"
SINON SI moyenne >= 14 ALORS mention ← "Bien"
SINON SI moyenne >= 12 ALORS mention ← "Assez bien"
SINON mention ← "Passable"
FIN SIÉtape 2 : Bloc de code avec commentaires de section
// ================================
// CALCUL DES STATISTIQUES ACADÉMIQUES
// ================================
// Initialisation des données
variable notes ← [12, 15, 8, 17, 14, 9, 16, 11, 13, 10]
// Calcul de la moyenne
variable somme ← 0
POUR note IN notes FAIRE
somme ← somme + note
FIN POUR
variable moyenne ← somme / LONGUEUR(notes)
// Calcul de l'écart-type (mesure de dispersion)
variable ecart_type ← 0
POUR note IN notes FAIRE
ecart_type ← ecart_type + (note - moyenne) * (note - moyenne)
FIN POUR
ecart_type ← RACINE(ecart_type / LONGUEUR(notes))
// Attribution de la mention selon la moyenne
variable mention ← ""
SI moyenne >= 16 ALORS mention ← "Très bien"
SINON SI moyenne >= 14 ALORS mention ← "Bien"
SINON SI moyenne >= 12 ALORS mention ← "Assez bien"
SINON mention ← "Passable"
FIN SI
// Les variables moyenne, ecart_type et mention sont maintenant disponiblesÉtape 3 : Analyse des sections commentées
Section d'initialisation : Précise les données d'entrée
Section de calcul de moyenne : Explique le but de ce calcul
Section d'écart-type : Indique la signification statistique
Section de mention : Explique la logique de classification
Bloc de code organisé avec commentaires de section
Organisation par sections :
Le code est maintenant clairement structuré en sections avec des commentaires descriptifs.
Règles de commentaire de bloc :
• Identifier les sections logiques : Regrouper par fonction
• Utiliser des séparateurs visuels : Pour distinguer les sections
• Expliquer le but de chaque section : Clarifier la logique
5 Documentation de module
Définition :
Problème : Créer une documentation complète pour un module de gestion
1
Rédiger l'en-tête du module
2
Documenter les fonctions
3
Expliquer les dépendances
4
Fournir des exemples d'utilisation
Étape 1 : Module de gestion de bibliothèque
/**
* Module de gestion de bibliothèque
*
* Ce module fournit des fonctions pour gérer les livres, les emprunts
* et les utilisateurs dans une bibliothèque.
*
* Auteur: Étudiant NSI
* Version: 1.0
* Date: Mars 2024
*/
// Structure pour représenter un livre
Structure Livre
isbn : Chaîne
titre : Chaîne
auteur : Chaîne
disponible : Booléen
Fin Structure
// Structure pour représenter un utilisateur
Structure Utilisateur
id : Entier
nom : Chaîne
email : Chaîne
Fin StructureÉtape 2 : Documentation des fonctions principales
/**
* Ajoute un nouveau livre à la bibliothèque
*
* @param isbn : Numéro ISBN du livre
* @param titre : Titre du livre
* @param auteur : Nom de l'auteur
* @return True si l'ajout est réussi, False sinon
*/
FONCTION AjouterLivre(isbn, titre, auteur) : Booléen
// Vérification que le livre n'existe pas déjà
SI RechercherLivreParISBN(isbn) ≠ NULL ALORS
RETOURNER FAUX
FIN SI
// Création du nouvel objet livre
nouveau_livre ← NOUVEAU Livre
nouveau_livre.isbn ← isbn
nouveau_livre.titre ← titre
nouveau_livre.auteur ← auteur
nouveau_livre.disponible ← VRAI
// Ajout à la collection
AJOUTER liste_livres, nouveau_livre
RETOURNER VRAI
FIN
/**
* Emprunte un livre par un utilisateur
*
* @param utilisateur_id : Identifiant de l'utilisateur
* @param isbn : ISBN du livre à emprunter
* @return True si l'emprunt est effectué, False sinon
*/
FONCTION EmprunterLivre(utilisateur_id, isbn) : Booléen
// Vérification de la disponibilité du livre
livre ← RechercherLivreParISBN(isbn)
SI livre = NULL OU NON livre.disponible ALORS
RETOURNER FAUX
FIN SI
// Marquer le livre comme indisponible
livre.disponible ← FAUX
// Enregistrer l'emprunt
AJOUTER historique_emprunts, (utilisateur_id, isbn, DATE_AUJOURDHUI())
RETOURNER VRAI
FINÉtape 3 : Documentation des constantes et exemples
/**
* Constantes du module
*/
constante MAX_EMPRUNTS_PAR_UTILISATEUR ← 5 // Limite d'emprunts simultanés
constante DUREE_EMPRUNT_JOURS ← 14 // Durée maximale d'emprunt
/**
* Exemple d'utilisation du module
*
* AJOUTER_LIVRE("978-0-123456-47-2", "Introduction à l'algorithmique", "Thomas H. Cormen")
* resultat ← EMPRUNTER_LIVRE(123, "978-0-123456-47-2")
* SI resultat = VRAI ALORS
* AFFICHER "Emprunt réussi"
* SINON
* AFFICHER "Emprunt impossible"
* FIN SI
*/
// Fin du module de gestion de bibliothèque
Module documenté avec en-tête, fonctions et exemples
Documentation complète :
Le module est entièrement documenté avec des en-têtes, des descriptions de fonctions et des exemples d'utilisation.
Règles de documentation de module :
• En-tête complet : Auteur, version, date, description
• Documentation des fonctions : Paramètres, retour, comportement
• Exemples d'utilisation : Montrer comment utiliser le module
Cours bien détaillé
Lisibilité_{code} = \frac{Commentaires_{utiles}}{Lignes_{code}} × 100\%
Calcul de la lisibilité du code
Objectif : Expliquer le code sans répéter l'évidence.
Pertinence : Se concentrer sur les parties complexes.
Concision : Être clair et bref.
Maintenance : Garder les commentaires à jour.
Conseil : Commenter pourquoi, pas comment
Attention : Ne pas commenter ce qui est évident
Astuce : Utiliser des commentaires de section pour organiser
Méthode : Suivre un style de documentation cohérent
Vérification : Lire le code comme un tiers
Types de commentaires utiles :
- Commentaires de documentation : Descriptifs de fonctions/classes
- Commentaires d'explication : Clarification de logique complexe
- Commentaires de section : Organisation du code
- Commentaires de TODO/FIXME : Points à améliorer
Règles importantes :
- Les commentaires doivent être mis à jour avec le code
- Éviter les commentaires redondants avec le code
- Utiliser un style de commentaire cohérent dans le projet
- Écrire les commentaires en français ou dans la langue du projet
Points clés à retenir :
- But : Les commentaires servent à clarifier le code, pas à le répéter
- Qualité : Mieux vaut quelques bons commentaires que beaucoup de mauvais
- Maintenance : Les commentaires doivent évoluer avec le code
- Collaboration : Les commentaires facilitent la collaboration entre développeurs
