Votre premier instinct de développeur est de ne pas être d’accord mais de m’écouter.
Je ne dis pas que les commentaires sont tous mauvais. S’ils sont utilisés correctement, les commentaires sont très puissants mais ils ne sont pas la réponse à votre désordre, ils peuvent en créer un autre.
Un code pourrait brillamment résoudre un problème critique en utilisant un algorithme bien conçu, en utilisant un célèbre modèle de conception ou en exploitant une caractéristique révolutionnaire d’un langage de programmation, tout en dépendant de la fourniture de commentaires à chaque étape du processus et pourtant être un mystère pour l’équipe de développeurs qui le maintient. Pourquoi ?
Certains développeurs ont tendance à se concentrer davantage sur la rédaction de commentaires qui font perdre du temps que sur la refonte du code lui-même. Voici quelques commentaires dont votre équipe se passera bien :
Commentaires redondants
Les commentaires doivent apporter une valeur ajoutée ou décrire une logique originale, et non traduire la syntaxe. Si le code a été bien écrit, il n’aura pas besoin de ce commentaire supplémentaire pour décrire le travail de chaque ligne.
Vous pouvez clairement voir ici que le commentaire est si peu utile, surtout avec toutes les désignations descriptives.
// The processor delay for this component. protected int processorDelay = -1;
Commentaires trompeurs
La route de l’enfer est pavée de bonnes intentions. L’auteur peut faire un commentaire inexact pour toutes les bonnes raisons, mais cela coûterait à un mauvais programmeur une session de débogage coûteuse.
Par exemple, la méthode utilisée ici ne revient pas lorsque this.closed devient true. Elle ne revient que si this.closed est true ; sinon, elle attend un time-out aveugle puis lance une exception si elle n’est toujours pas fermée. La différence est stupéfiante !
// Returns when this.closed is true. Throws an exception on timeout is reached.
public synchronized void waitForClose(final long timeoutMillis) throws Exception
{
if(!closed){
wait(timeoutMillis);
if(!closed)
throw new Exception("MockResponseSender could not be closed");
}
}
Commentaires obligatoires
Certains commentaires obligatoires pourraient ne pas être très utiles après tout. Les commentaires ne doivent pas être un simple fouillis.
Les javadocs ici ne sont que du désordre.
/**
* @param title The title of the CD
* @param author The author of the CD
*/
public void addCD(String title, String author) {
CD cd = new CD();
cd.title = title;
cd.author = author;
cdList.add(cd);
}
Bruit dans les commentaires
Les commentaires doivent fournir de nouvelles informations, sinon ils ne sont que du bruit que nous apprenons à ignorer. Si vous ignorez un commentaire, cela signifie qu’il n’aurait pas dû être là en premier lieu.
Non seulement cet auteur a écrit un commentaire inutile, mais il a également oublié d’ajouter le corps de la prise et a laissé un commentaire marmonné sans contexte.
try
{
// Continue normal flow
doSomething();
}
catch(Exception e1)
{
// Give me a break!
}
Long commentaires ou longues phrases
De longs commentaires qui sont utilisés pour décrire chaque décision que vous avez prise. Ces commentaires peuvent expliquer chaque ligne en détail : pourquoi vous avez choisi de l’écrire de cette façon, quelles étaient les alternatives, quel est l’historique du code qui y a conduit. Il est très difficile de lire le code couramment, et cela peut créer une confusion supplémentaire pour le lecteur. Au final, cela fait plus de mal que de bien. Essayez de faire des commentaires aussi courts que possible avec un minimum de contexte.
Si la raison pour laquelle vous ajoutez un commentaire est que le code est hacky ou compliqué, rendez-le lisible en le remaniant – et non en ajoutant une autre couche de confusion. Choisissez de meilleurs noms, interrompez les fonctions pour faire une chose et utilisez des abstractions. Tout ce dont vous avez besoin pour rendre votre code plus lisible, faites-le avec du code, pas avec des commentaires.
// Async edge case #6566 requires saving the timestamp when event listeners are
// attached. However, calling performance.now() has a perf overhead especially
// if the page has thousands of event listeners. Instead, we take a timestamp
// every time the scheduler flushes and use that for all event listeners
// attached during that flush.
export let currentFlushTimestamp = 0
// Async edge case fix requires storing an event listener's attach timestamp.
let getNow: () => number = Date.now
// Determine what event timestamp the browser is using. Annoyingly, the
// timestamp can either be hi-res (relative to page load) or low-res
// (relative to UNIX epoch), so in order to compare time we have to use the
// same timestamp type when saving the flush timestamp.
if (inBrowser && getNow() > document.createEvent('Event').timeStamp) {
// if the low-res timestamp which is bigger than the event timestamp
// (which is evaluated AFTER) it means the event is using a hi-res timestamp,
// and we need to use the hi-res version for event listeners as well.
getNow = () => performance.now()
}
Commentaires de substitution de fonctions ou de variables
Une ligne de code complexe n’a pas besoin de commentaire, ce dont elle a besoin, c’est d’être remaniée ou divisée en composants plus petits.
Vérifiez cette reformulation, c’est étonnant, non ?
// does the module from the global list <mod> depend on the
// subsystem we are part of?
if (smodule.getDependSubsystems().contains(subSysMod.getSubSystem())) { }
Reformulation
ArrayList moduleDependees = smodule.getDependSubsystems();
String ourSubSystem = subSysMod.getSubSystem();
if (moduleDependees.contains(ourSubSystem)) { }
Commentaires du marqueur de position
Marquer un poste particulier d’un commentaire est rarement utile ; il est logique de regrouper certaines fonctions sous une bannière. Mais je ne vois pas l’utilité de cela pour chaque fonction, en général, elles peuvent en fait n’être qu’un fouillis.
Admettez que vous avez fait cela 😉
// Actions //////////////////////////////////
Attribution Commentaires
Il n’est pas nécessaire de polluer le code avec des petites signatures. Il y a tellement d’outils de contrôle des sources qui sont très efficaces pour se rappeler qui a ajouté quoi, quand.
La faute est après nous tous, je me sens tellement exposé…
Code commenté
Les sections commentées ne sont pas trop importantes à supprimer. En fait, la plupart des systèmes de contrôle du code source se souviennent du code pour nous. Nous n’avons plus besoin d’accumuler des morceaux inutiles de code inactif.
Vous vous souvenez de la première fois où vous avez découvert que vous étiez collant ?
InputStreamResponse response = new InputStreamResponse(); response.setBody(formatter.getResultStream(), formatter.getByteCount()); // InputStream resultsStream = formatter.getResultStream(); // StreamReader reader = new StreamReader(resultsStream); // response.setContent(reader.read(formatter.getByteCount()));
Commentaires non locaux
Les commentaires doivent décrire le code dont il est proche. Il doit y avoir un lien évident entre le code et les commentaires.
N’offrez pas d’informations non pertinentes ou générales dans le contexte d’un commentaire local. Les discussions historiques intéressantes ou les descriptions non pertinentes de détails ne sont pas des commentaires.
Références
Cet article est basé sur le Clean Code : A Handbook of Agile Software Craftsmanship de Robert C. Martin, il est fortement recommandé de lire ce livre, un livre si étonnant qui vous apportera beaucoup.
