Chapitre 4 – Les Commentaires

Dans le chapitre 4 de "Clean Code", Robert C. Martin aborde un sujet fondamental et souvent mal compris : les commentaires dans le code. Contrairement à ce que l'on pourrait penser, l'auteur ne recommande pas d'ajouter systématiquement des commentaires, mais plutôt de les utiliser avec parcimonie et uniquement lorsqu'ils apportent une réelle valeur. Ce chapitre est particulièrement pertinent pour les développeurs React et TypeScript, où un code expressif peut souvent remplacer avantageusement les commentaires.

Points essentiels à retenir:

  • Les commentaires ne compensent pas un code mal écrit - améliorez d'abord votre code
  • Les meilleurs commentaires sont ceux que vous n'avez pas besoin d'écrire
  • Les commentaires deviennent souvent obsolètes et inexacts avec le temps
  • Utilisez TypeScript et des noms expressifs plutôt que des commentaires explicatifs

1. Le paradoxe des commentaires

Robert C. Martin commence ce chapitre par une affirmation provocante : "Les commentaires sont, au mieux, un mal nécessaire". Cette position peut sembler contre-intuitive, surtout pour les développeurs junior habitués à entendre qu'il faut "bien commenter son code". L'auteur explique que les commentaires tentent souvent de compenser un code peu clair ou mal structuré, alors que la véritable solution serait de rendre le code lui-même plus expressif.

Hiérarchie des commentaires Code auto-explicatif (Pas de commentaires) Commentaires légaux et informatifs Clarification d'intention Avertissements TODO Fréquence d'utilisation Nécessité

Temps estimé pour appliquer les principes : 2-3 heures par semaine

Pour transformer progressivement votre approche des commentaires, prévoyez environ 2-3 heures par semaine pour analyser et refactoriser votre code existant. C'est un investissement qui, selon les études, peut réduire le temps de maintenance d'environ 20% à long terme.

2. Les bons commentaires vs. les mauvais commentaires

Tous les commentaires ne se valent pas. Martin distingue clairement ceux qui ajoutent de la valeur de ceux qui créent de la confusion ou deviennent rapidement obsolètes. Dans un environnement React/TypeScript moderne, cette distinction est encore plus cruciale.

Les bons commentaires (à utiliser avec parcimonie)

Certains types de commentaires sont considérés comme acceptables, voire nécessaires dans certains contextes. Voici les catégories que Martin identifie :

  • Commentaires légaux : Copyright, licences (1h pour mettre en place)
  • Commentaires informatifs : Expliquer la signification d'un format ou d'une regex complexe (30min par cas)
  • Clarification d'intention : Quand le code ne peut pas être suffisamment clair par lui-même (15min de réflexion)
  • Avertissements : Prévenir des conséquences non évidentes (10min par cas)
  • Commentaires TODO : Rappels temporaires d'actions à accomplir (5min, à examiner régulièrement)
  • Documentation publique (JSDoc/TSDoc) : Pour les API exposées (45min par fonction documentée)

Exemples de bons commentaires en React/TypeScript

// Bon exemple : commentaire légal
/**
 * Copyright (c) 2025 Votre Entreprise
 * Ce fichier est soumis à la licence MIT
 */

// Bon exemple : commentaire informatif sur un regex complexe
// Format: YYYY-MM-DD où la date doit être valide
const dateRegex = /^(\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$/;

// Bon exemple : avertissement important
// ATTENTION: Cette fonction mutate l'objet passé en paramètre
function sortInPlace(array: number[]): void {
  // Implémentation...
}

// Bon exemple : documentation d'API avec JSDoc/TSDoc
/**
 * Récupère les données d'un utilisateur depuis l'API
 * @param userId - L'identifiant unique de l'utilisateur
 * @returns La promesse contenant les données utilisateur
 * @throws {ApiError} Si l'utilisateur n'est pas trouvé
 */
async function fetchUserData(userId: string): Promise<UserData> {
  // Implémentation...
}
            

Les mauvais commentaires (à éviter)

Martin identifie plusieurs types de commentaires qui nuisent plus qu'ils n'aident, et que vous devriez activement chercher à éliminer de votre code :

  • Commentaires redondants : Répètent ce que le code dit déjà clairement (1h pour identifier et supprimer)
  • Commentaires trompeurs : Inexacts ou obsolètes (2h d'audit)
  • Commentaires obligatoires : Ajoutés par obligation, sans valeur (30min pour revoir les standards)
  • Journaux et historiques : Traces des modifications passées (utiliser Git à la place, 15min de formation)
  • Bruit : Commentaires qui n'apportent aucune information (45min pour nettoyer)
  • Code commenté : Ancien code laissé en commentaires (1h pour nettoyer avec Git)

Exemples de mauvais commentaires à éviter

// Mauvais exemple : commentaire redondant qui répète le code
// Incrémente le compteur
count++;

// Mauvais exemple : commentaire obsolète
// La fonction retourne un tableau de chaînes
function getUsers(): User[] { // Retourne maintenant des User, pas des chaînes
  // Implémentation...
}

// Mauvais exemple : commentaire obligatoire sans valeur
/**
 * @function processData
 * @param {object} data - Les données
 * @returns {object} - Les données traitées
 */
function processData(data: object): object {
  // Implémentation...
}

// Mauvais exemple : code commenté
function calculateTotal(items: Item[]): number {
  let total = 0;
  for (const item of items) {
    total += item.price;
  }
  // const tax = total * 0.2;
  // total += tax;
  return total;
}
            

3. Application dans l'écosystème React/TypeScript

Dans le contexte spécifique de React et TypeScript, les principes de Clean Code concernant les commentaires prennent une dimension particulière. TypeScript, avec son système de types expressif, et React, avec sa structure déclarative, offrent de puissantes alternatives aux commentaires.

TypeScript comme alternative aux commentaires (2h d'apprentissage initial)

TypeScript permet d'exprimer des intentions et des contraintes directement dans le code, rendant de nombreux commentaires explicatifs superflus :

TypeScript vs Commentaires

// Avec commentaires en JavaScript
/**
 * @param {string} name - Le nom de l'utilisateur
 * @param {number} age - L'âge, doit être >= 18
 * @param {string[]} roles - Liste des rôles de l'utilisateur
 * @returns {Object} L'objet utilisateur créé
 */
function createUser(name, age, roles) {
  if (age < 18) throw new Error("L'âge doit être supérieur à 18");
  // Reste de l'implémentation...
}

// Avec TypeScript (sans commentaires nécessaires)
interface User {
  name: string;
  age: number;
  roles: string[];
}

function createUser(
  name: string, 
  age: number, 
  roles: string[]
): User {
  if (age < 18) throw new Error("L'âge doit être supérieur à 18");
  // Reste de l'implémentation...
}
            

Composants React auto-explicatifs (3h de restructuration)

La structure compositionnelle de React permet de créer des composants dont le nom et la structure expliquent naturellement leur fonction, réduisant le besoin de commentaires explicatifs :

Composants React auto-explicatifs

// Avec commentaires (à éviter)
// Ce composant affiche un formulaire de connexion
// avec validation et gestion des erreurs
function AuthForm({ onSubmit }) {
  // État pour stocker les données du formulaire
  const [formData, setFormData] = useState({});
  // État pour gérer les erreurs
  const [errors, setErrors] = useState({});
  
  // ...reste du code
}

// Sans commentaires, auto-explicatif (préférable)
function LoginForm({ onSubmit }: LoginFormProps) {
  const [credentials, setCredentials] = useState<Credentials>({ 
    email: '', 
    password: '' 
  });
  const [validationErrors, setValidationErrors] = useState<ValidationErrors>({});
  
  const validateForm = (): boolean => {
    // Logique de validation...
  };
  
  const handleSubmit = (e: React.FormEvent): void => {
    e.preventDefault();
    if (validateForm()) {
      onSubmit(credentials);
    }
  };
  
  return (
    <form onSubmit={handleSubmit}>
      <EmailInput 
        value={credentials.email}
        onChange={handleEmailChange}
        error={validationErrors.email}
      />
      <PasswordInput 
        value={credentials.password}
        onChange={handlePasswordChange}
        error={validationErrors.password}
      />
      <SubmitButton disabled={!isFormValid()} />
    </form>
  );
}
            

Principe de responsabilité unique (SRP) (4h de refactorisation)

En suivant le principe de responsabilité unique, vous créez naturellement des composants et des fonctions plus petits et plus focalisés, réduisant le besoin de commentaires explicatifs :

Application du SRP pour éviter les commentaires

// Avec une fonction qui fait trop de choses (nécessite des commentaires)
function processUserData(userData: any) {
  // Validation des données
  if (!userData.name) throw new Error("Nom manquant");
  if (userData.age < 18) throw new Error("Âge minimum 18 ans");
  
  // Transformation des données
  const processedData = {
    fullName: `${userData.name} ${userData.surname || ''}`.trim(),
    isAdult: userData.age >= 18,
    // ...autres transformations
  };
  
  // Sauvegarde en base de données
  saveToDatabase(processedData);
  
  // Envoi d'email de confirmation
  sendConfirmationEmail(userData.email);
  
  return processedData;
}

// Avec SRP (pas besoin de commentaires)
function validateUserData(userData: UserInput): void {
  if (!userData.name) throw new Error("Nom manquant");
  if (userData.age < 18) throw new Error("Âge minimum 18 ans");
}

function transformUserData(userData: UserInput): UserData {
  return {
    fullName: `${userData.name} ${userData.surname || ''}`.trim(),
    isAdult: userData.age >= 18,
    // ...autres transformations
  };
}

function processUserRegistration(userData: UserInput): UserData {
  validateUserData(userData);
  const processedData = transformUserData(userData);
  saveToDatabase(processedData);
  sendConfirmationEmail(userData.email);
  return processedData;
}
            

À Retenir

  • Objectif primaire : Écrire un code si clair qu'il ne nécessite pas de commentaires (3h d'effort initial, économie de 8h/mois)
  • Commentaires comme dernier recours : À n'utiliser que lorsque vous ne pouvez pas rendre le code plus expressif (évaluation : 30min par cas)
  • Maintenance des commentaires : Tout commentaire crée une dette technique potentielle car il doit être maintenu à jour (coût : 1h/semaine en maintenance)
  • TypeScript comme documentation : Exploitez le système de types pour auto-documenter votre code (gain : 4h/semaine)
  • Composants React bien nommés : Des noms clairs et des structures logiques remplacent efficacement les commentaires (gain : 2h/semaine en revue)