Section courante

A propos

Section administrative du site

Documentation et commentaires

Les commentaires font partie de la documentation interne, tandis que la documentation peut être externe ou générée automatiquement.

Pourquoi documenter et commenter

Lisibilité

Maintenance

Collaboration

Réutilisation et formation

Types de commentaires

Commentaires sur une ligne

Commentaires multi-lignes / blocs

Pour expliquer des sections plus longues ou complexes. En langage de programmation C :

  1. /* Calcul de la moyenne :
  2.    On additionne toutes les notes et on divise par le nombre total */

En langage de programmation Pascal :

  1. { Calcul de la moyenne :
  2.   On additionne toutes les notes et on divise par le nombre total }

Commentaires de documentation

Bonnes pratiques pour commenter

Documentation externe

Exemples pratiques

Exemple C++

  1. #include <stdio.h>
  2.  
  3. /**
  4.  * Affiche un message de bienvenue
  5.  * @param nom Nom de l'utilisateur
  6.  */
  7. void saluer(const char *nom) {
  8.     printf("Bonjour %s!\n", nom);
  9. }
  10.  
  11. int main() {
  12.     saluer("Alice"); // Appel de la fonction saluer
  13.     return 0;
  14. }

Exemple Free Pascal

  1. Program ExempleDocumentation;
  2.  
  3. (**
  4. Affiche un message de bienvenue
  5. @param nom Nom de l'utilisateur
  6. **)
  7. Procedure Saluer(nom:String);Begin
  8.  Writeln('Bonjour ', nom, ' !');  // Affiche le message
  9. End;
  10.  
  11. BEGIN
  12.   Saluer('Alice'); // Appel de la procédure
  13. END.

Stratégies avancées

Marquer les zones à revoir

Documenter les algorithmes complexes

Automatisation

Utiliser des outils comme Doxygen, Javadoc, Sphinx pour générer la documentation à partir des commentaires

Avantages de la documentation et des commentaires

Avantage Explication
Lisibilité Compréhension immédiate du code
Maintenabilité Facilite la correction et la modification
Réutilisabilité Permet de réutiliser les fonctions sans lire tout le code
Collaboration Tous les développeurs parlent le même langage

Traçabilité Historique des modifications et des intentions

Transition vers la POO

Exemple : Documenter une classe TCompteBancaire avec ses méthodes RetirerArgent et DeposerArgent.

Résumé

Règle d'or : un code sans commentaires et documentation est lisible seulement pour son auteur et seulement pendant quelques semaines.



Dernière mise à jour : Jeudi, le 1er janvier 2026