Pourquoi je commente mon code ?

Clean Code Je suis en train de lire le livre Clean Code de Robert C. Martin. Je suis d’accord avec tout ce qu’il dit sauf une chose, les commentaires de code.

Je sais qu’il y a plein de développeurs qui justifient l’absence de commentaires. On va les énumérer.

Les commentaires sont inutiles

Les commentaires sont inutiles au fonctionnement de l’application. Oui, c’est vrai, même chose pour les noms des méthodes explicites.

Faire fonctionner une application est une chose, mais la maintenir en est une autre. Tout le problème est justement la maintenance.

Donc on crée une architecture adaptée et versatile, on choisit des noms de classes pour coller au métier, on range les fichiers dans une logique, on nomme les méthodes et variables pour comprendre facilement l’ensemble.

On écrit du code pour qu’il soit lisible. On code pour que d’autres développeurs le lisent. Tous les outils qui aident à la comprehension de l’application sont utiles.

Les noms des méthodes sont explicites

Au delà de 4 mots, j’ai du mal à lire une méthode en camelCase.

Exemple en PHP :

// Get total amount including tax
public function getTotalAmountIncludingTax()

Je fais exprès de donner un exemple où le commentaire est exactement le nom de la méthode.

L’auteur du livre annonce comme une évidence que le commentaire n’est pas plus lisible que le nom de la fonction. Je trouve personnellement que c’est le contraire.

D’autres exemples en Javascript :

// Filter orders of type "renewal"
filterRenewalOrders(orders:Array<Order>):Array<Order>

// Filter orders of type "renewal" and paid (not free)
filterPaidRenewalOrders(orders:Array<Order>):Array<Order>

Et des exemples qui viennent du livre même (en Java) :

public void turnOnLoTempAlarmAtThreshold() throws Exception {
public void turnOnCoolerAndBlowerIfTooHot() throws Exception {
private static boolean isNotMultipleOfAnyPreviousPrimeFactor(int candidate) {
private static void checkOddNumbersForSubsequentPrimes() {

Je ne dénonce pas la longueur des noms de méthodes. Je veux mettre en évidence qu’au bout d’un moment, c’est difficile à lire.

Suivant le langage, il y a d’autres nuisances qui polluent la lisibilité comme le typage et la visibilité.

Les méthodes sont courtes et faciles à comprendre

Je suis tout à fait d’accord, c’est l’idéal.

Une méthode qui entre entièrement dans l’écran, on peut la lire facilement sans scroller. Le nom est explicite et l’implémentation est limpide.

On devrait tous tendre vers ce genre de méthode, mais malheureusement on n’a pas tous le niveau nécessaire. Réussir à découpler correctement son code, à l’organiser et à rendre l’ensemble compréhensible, ce n’est pas si facile.

Je préfère largement qu’un développeur commence avec une méthode un peu longue commentée avec des étapes dans le raisonnement. Il le refactorera plus tard en découpant en fonctions plus petites. S’il a écrit les tests et que sa fonctionnalité marche, c’est déjà énorme.

Dans la réalité, on peut être amené à changer de tâche, avoir un imprévu, avoir une longue réunion, etc. Si vos commits sont petits et que vous avancez bien avec des tests, après une interruption, vous pouvez reprendre plus rapidement là où vous en étiez grâce aux commentaires d’étapes.

Le code s’auto-documente lui même

Oui, si on prend le temps de lire le code, tout s’explique.

Je prend encore un exemple du livre (en Java) :

public static String renderPageWithSetupsAndTeardowns(PageData pageData, boolean isSuite) throws Exception {
    if (isTestPage(pageData))
        includeSetupAndTeardownPages(pageData, isSuite);
    return pageData.getHtml();
}

Évidemment, cette méthode n’est pas isolée, elle est parmi d’autres parce que le code est découpé en petites fonctions.

J’aurai rajouté un commentaire pour la méthode entière parce qu’elle est courte :

/**
 * Render page
 * Include setup and teardown pages if it is a test page
 */
public static String renderPageWithSetupsAndTeardowns(PageData pageData, boolean isSuite) throws Exception {
    if (isTestPage(pageData))
        includeSetupAndTeardownPages(pageData, isSuite);
    return pageData.getHtml();
}

Lorsque je lis en diagonal par exemple, je trouve et je lis plus facilement le commentaire. Et moi qui change souvent de langage, il n’y a pas beaucoup de différence dans l’écriture des commentaires, pas de pollution lié au langage.

Les commentaires sont une nuisance visuelle

Prenons plus de recul maintenant (littéralement).

Le code idéal

Code visuel 01 Je prend l’exemple du code idéal.

Pour les habitués, on peut distinguer facilement :

La réalité

Code visuel 02 Mais le code est rarement idéal. Là ça commence à être plus difficile, et je n’ai pas poussé l’exercice plus loin parce que ça allait donner une image trop grande.

Il y a :

Avec la colorisation syntaxique, on voit de la déclaration de variables, des IFs, une boucle, des valeurs de retours et un peu d’espacement entre les traitements.

Le code avec commentaires

Code visuel 03 Et oui, c’est plus long, forcément.

Il y a toujours :

J’ai rajouté un peu de Javadoc pour accentuer la hauteur des commentaires qui ne prennent en général pas qu’une seule ligne. Il y a aussi quelques commentaires dans l’implémentation des méthodes.

Je trouve que les commentaires marquent verticalement le code.

Les commentaires ne sont pas maintenus

L’argument ici est de dire qu’un commentaire est rarement modifié lorsque le code associé l’est.

J’appelle ça de la négligence de la part du développeur.

Il n’y a pas de tests qui vérifient les commentaires, contrairement au code. L’argument pointe le fait que les développeurs modifient rarement ce qu’il a autour du code. Et c’est vrai, mais cela reste une négligence.

Les schémas UML et la documentation sont dans le même cas. Ils aident à la comprehension de l’application et il faut les maintenir au même titre que le code.

Lorsqu’un nouveau développeur arrive dans une équipe, on va lui expliquer comment l’ensemble fonctionne. Il y a d’abord tout ce qui est lié au métier, ensuite l’architecture, puis les conventions de code, etc.

Si vous ne maintenez pas vos documents (et commentaires), alors il est plus difficile d’entrer dans le code. Pire, vous pouvez induire les autres en erreur avec des explications obsolètes. Vous ne vous rendez pas compte parce que vous êtes dans le domaine depuis un moment, voire vous l’avez conçu.

Les commentaires ne masquent pas le mauvais code

Parfois, vous écrivez un code qui ne vous plaît pas et vous le savez. Vous êtes alors tenté de mettre un commentaire au dessus pour expliquer l’intention. Dans le livre Clean Code, l’auteur dit que cela ne sert à rien, il faut plutôt mieux écrire.

OK … super, c’est évident, mais ce n’est pas la réalité, je suis désolé.

Je suis d’accord qu’il faut tendre vers un bon code, mais en attendant, il faut qu’il soit quand même lisible.

En plus, le commentaire décrit l’intention. Il arrive que le code associé n’est finalement pas bien exécuté, c’est un bug quoi. Évidemment, on parle d’un cas métier qui n’a pas été testé, et le commentaire le décrit.

// Total amount must be positive
if (totalAmount != 0) {
    validOrderCount++;
}

On découvre qu’il y a un bug en production et en regardant le code, on remarque que la condition aurait dû utiliser >=.

Les développeurs sont fainéants

Je pense surtout que ceux qui n’aiment pas écrire des commentaires s’engouffrent dans cette règle de Clean Code parce que ça les arrange bien.

Mais ne me faites pas croire que tous les développeurs savent écrire des classes et des méthodes Clean du premier coup, et qu’en plus, ils ont le temps.

Dans la réalité, on s’attarde déjà sur l’architecture, ensuite on implémente. Devant un algorithme métier qu’on est en train d’écrire, on valide déjà que cela marche et que les tests passent. Enfin, on clean en découpant si on a le temps.

Il y a des découpages plus faciles que d’autres. Parfois, il suffit de créer des méthodes dans la même classe. Parfois, on se rend compte qu’il faut plutôt découpler vers un autre service. Dans le pire des cas, il faut architecturer autrement pour garder l’algorithme simple.

Les commentaires ne sont pas faciles à écrire

Comme n’importe quelle documentation, il n’est pas facile d’écrire de bons commentaires.

Il y a un aspect pédagogique. Tout le monde ne sait pas expliquer (avec des mots ou des schémas) de façon efficace.

Et parfois, en tentant d’expliquer un algorithme, on le comprend encore mieux, voire on le corrige.

L’éditeur

Il y a pas mal d’éditeurs qui ont le code folding, cela peut aider à cacher les nuisances pour certains.

Il y a aussi le listing des méthodes, trié par ordre alphabétique.

L’IntelliJ est sympa aussi pour la complétion.

Je pense qu’avec les outils qu’on a à notre disposition, il est plus préjudiciable d’avoir un code sans commentaires plutôt que l’inverse.

Conclusion

Tenter de bien écrire du premier coup, ce n’est pas impossible. Mais je pense qu’il faut réunir pas mal de critères. S’il y a un architecte qui guide toute l’équipe, alors je pense que c’est possible.

Ne me faites pas croire que tous les développeurs sont capables d’écrire du Clean Code. Il faut avoir en tête qu’il y a tous les niveaux. Les équipes changent tout le temps.

Si vous êtes une équipe d’élites, faites ce que vous voulez avec votre code sans commentaires. Mais si vous vous souciez que votre code soit lisible par le plus grand monde, commentez-le !

Commentaires