Définitions & Concepts
Code + Documentation = Maintenabilité
Explication du fonctionnement du programme
Documentation : Explication du code
Commentaires : Notes dans le code
Manuel : Guide externe
Exemple de commentaire :
def tri_bulle(tab):
# Trie un tableau en ordre croissant
# Paramètre: tab - liste de nombres
# Retourne: liste triée
# Trie un tableau en ordre croissant
# Paramètre: tab - liste de nombres
# Retourne: liste triée
Règle fondamentale :
Documenter les intentions, pas les évidences
Types de documentation
Inline : Commentaires dans le code
Bloc : Explications détaillées
Externe : Fichiers séparés
API : Documentation des fonctions
Maintenance : Suivi des modifications
Formules de lisibilité
Ratio commentaire/code :
RC = (Lignes_commentées / Lignes_code) × 100
Recommandé : 15-25%
Recommandé : 15-25%
Bonnes pratiques
Clarté : Langage simple et précis
Mise à jour : Synchronisation avec le code
Nommage : Variables et fonctions explicites
Structure : Format cohérent
Collaboration : Pour les autres développeurs
Règles essentielles
Règle du pourquoi :
Expliquer pourquoi le code fait quelque chose, pas comment
Exemples d'utilisation :
Fournir des exemples d'appel de fonctions
Maintenabilité :
Faciliter la compréhension future du code
