Les commentaires peuvent parfois nuire à la lisibilité du code lorsqu’ils sont utilisés de manière inappropriée. Cependant, il y a des moments où ils sont absolument essentiels. Robert C. Martin a mis en lumière huit circonstances où les commentaires sont pertinents.

« Bien qu’il y ait des commentaires qui ajoutent de la valeur, rappelons-nous que le commentaire le plus efficace est celui que nous n’avons pas besoin d’insérer.

• Commentaires Juridiques : Des exigences légales ou des conventions d’entreprise peuvent nécessiter l’inclusion de commentaires, comme les mentions de droit d’auteur. Par exemple, je commence mes fichiers source avec un commentaire comme celui-ci dans FitNesse. Mon environnement de développement le minimise automatiquement, évitant ainsi un encombrement visuel. Il n’est cependant pas recommandé d’inclure des détails contractuels dans les commentaires. Référez-vous plutôt à un document ou à une licence externe.

// Copyright (C) 2003,2004,2005 par Object Mentor, Inc. Tous droits réservés.
// Publié sous les termes de la Licence Publique Générale de GNU version 2
// ou ultérieure.

• Commentaires Explicatifs : Il est parfois utile d’ajouter un commentaire pour clarifier le fonctionnement d’une méthode. Toutefois, il est souvent préférable que le nom de la méthode reflète sa fonction. Une expression régulière, par exemple, pourrait être mieux située dans une classe dédiée, rendant ainsi le commentaire superflu.

// Retourne une instance du Responder en cours de test.
protected abstract Responder responderInstance();

• Justification des Décisions : Les commentaires peuvent également expliquer pourquoi une certaine approche a été choisie. Il peut s’agir de précisions sur un tri spécifique ou d’une stratégie de test multithread.

public int compareTo(Object o) {
  if(o instanceof WikiPagePath) {
    WikiPagePath p = (WikiPagePath) o;
    String compressedName = StringUtil.join(names, "");
    String compressedArgumentName = StringUtil.join(p.names, "");
    return compressedName.compareTo(compressedArgumentName);
  }
  return 1; // Nous sommes supérieurs car nous sommes du bon type.
}

• Éclaircissements : Ils servent à détailler un segment de code ou une méthode. Il faut cependant s’assurer que ces commentaires sont exacts pour éviter la confusion.

public void testCompareTo() throws Exception {
  WikiPagePath a = PathParser.parse("PageA");
  WikiPagePath ab = PathParser.parse("PageA.PageB");
  WikiPagePath b = PathParser.parse("PageB");
  WikiPagePath aa = PathParser.parse("PageA.PageA");
  WikiPagePath bb = PathParser.parse("PageB.PageB");
  WikiPagePath ba = PathParser.parse("PageB.PageA");
 
  assertTrue(a.compareTo(a) == 0); // a == a
  assertTrue(a.compareTo(b) != 0); // a != b
  assertTrue(ab.compareTo(ab) == 0); // ab == ab
  assertTrue(a.compareTo(b) == -1); // a < b
  assertTrue(aa.compareTo(ab) == -1); // aa < ab
  assertTrue(ba.compareTo(bb) == -1); // ba < bb
  assertTrue(b.compareTo(a) == 1); // b > a
  assertTrue(ab.compareTo(aa) == 1); // ab > aa
  assertTrue(bb.compareTo(ba) == 1); // bb > ba
}

• Mise en Garde : Parfois, il est judicieux d’avertir d’éventuelles implications ou dangers liés à un certain code.

// Ne pas exécuter, à moins que
// vous ayez du temps à tuer.
  public void _testWithReallyBigFile() {
  writeLinesToFile(10000000);
  response.setBody(testFile);
  response.readyToSend(this);
  String responseString = output.toString();
  assertSubString("Content-Length: 1000000000", responseString);
  assertTrue(bytesSent > 1000000000);
}

• Commentaires TODO : Ils sont utilisés pour marquer des éléments qui nécessitent une attention future. Ils doivent être utilisés avec parcimonie et examinés régulièrement. Des modules de VS Code comme « Todo Tree » permettent de les gérer efficacement.

// TODO-MdM ce n’est pas nécessaire.
// Elle devrait disparaître lorsque nous implémenterons le modèle d’extraction.
protected VersionInfo makeVersion() throws Exception {
  return null;
}

• Mise en Exergue : Certains commentaires peuvent accentuer l’importance d’une action particulière qui pourrait autrement être négligée.

String listItemContent = match.group(3).trim();
// L’appel à trim est très important. Il retire les espaces
// de tête qui pourraient faire croire que l’élément est
// une autre liste.
new ListItemWidget(this, listItemContent, this.level + 1);
return buildList(text.substring(match.end()));

• Documentation des API Publiques : La documentation intégrée, comme Javadoc ou les commentaires « /// » en C#, est précieuse pour ceux qui utilisent l’API. Toutefois, cette documentation doit être précise et bien entretenue.

Gardons toujours à l’esprit que les commentaires doivent apporter une valeur ajoutée et non obscurcir ou induire en erreur. »