Résumer les croyances de la communauté autour du code de commentaire

Comme c'est souvent le cas sur mon site web, j'aime écrire des articles en réponse aux questions des étudiants. Cette fois-ci, j'ai reçu une question sur les priorités en matière de codage. Par exemple, est-il plus important que le code soit lisible ou correct ? Naturellement, je n'ouvrirai pas cette boîte de Pandore aujourd'hui, mais je parlerai d'une discussion indirecte qui est sortie de cette question :pourquoi je commente le code en dernier recours.

Normalement, quand j'écris un article comme celui-ci, je vide un peu mes pensées. Ensuite, je reviens en arrière et je le modifie jusqu'à ce qu'il soit beau et propre. Cette fois, je ne ferai pas ça. Au lieu de cela, je partagerai mon opinion telle que je l'ai partagée avec l'élève avec un raisonnement limité, juste quelques conseils généraux.

Après cela, je partagerai une tonne de points de vue de la communauté avec différents degrés de prise en charge pour commenter le code. Enfin, je résumerai toutes les vues avec mes plats à emporter. C'est marrant? Je l'espère !

Je commente le code en dernier recours

Quand j'ai appris à coder pour la première fois, je n'avais que 18 ans. À l'époque, j'avais appris que commenter du code était une bonne chose et que je devais le faire aussi souvent que possible. Au fur et à mesure que je poursuivais mes cours, j'ai reçu des dizaines de commentaires positifs sur mon style de codage, ce qui n'a fait que renforcer le comportement.

Voici à quoi ressemblait une partie de mon premier programme :

/* Returns the current cash balance for the the account
 */
public double getBalance() {
    return balance;
}
  
/* Adds amount to account cash balance
 */
public void pay(double amount) {
    balance = (balance + amount);
}  
  
/* Returns the current minute balance for the account
 */
public int getMinuteBalance() {
    return minuteBalance;
}

Et voici à quoi ressemblait le code dans mon projet senior :

/**
 * Start device discovery with the BluetoothAdapter
 */
private void doDiscovery() {
    if (D) Log.d(TAG, "doDiscovery()");

    // Indicate scanning in the title
    setProgressBarIndeterminateVisibility(true);
    setTitle(R.string.scanning);

    // Turn on sub-title for new devices
    findViewById(R.id.title_new_devices).setVisibility(View.VISIBLE);

    // If we're already discovering, stop it
    if (mBtAdapter.isDiscovering()) {
        mBtAdapter.cancelDiscovery();
    }

    // Request discover from BluetoothAdapter
    mBtAdapter.startDiscovery();
}

De toute évidence, j'ai aimé commenter le code. J'avais l'habitude d'ajouter une petite explication à presque tout ce que j'écrivais, et j'étais régulièrement félicité pour cela.

Ensuite, je suis allé dans l'industrie et j'ai trouvé que le paysage du codage était un peu plus compliqué. Le code était extrêmement dynamique et les exigences changeaient de jour en jour.

Naturellement, ces gentils commentaires se sont rapidement transformés en champ de mines. Si je n'étais pas diligent lors de la mise à jour du code, je me retrouverais à laisser les commentaires inchangés. Plus tard, ces commentaires revenaient me hanter. Ou pire, ils confondraient quelqu'un d'autre.

Maintenant, je me retrouve dans le camp que le code devrait être largement auto-documenté. En d'autres termes, les noms de variables et de fonctions doivent être descriptifs. De même, le code devrait être plus modulaire et sans effets secondaires. Par conséquent, plus récemment, mon code ressemble à ceci :

/**
 * Generates an HTML list item from some text.
 *
 * @param text
 *            the text to be listed
 * @return an HTML list item
 * @requires |text| > 0
 * @ensures [an HTML list item is generated in the form
 *          <li>text</li>]
 */
private static String generateListItem(String text) {
        assert text != null : "Violation of: text is not null";
        assert text.length() > 0 : "Violation of: text is not empty";
        String listItem = String.format("<li>%s</li>", text);
        return listItem;
}

/**
 * Generates an HTML link from some text and a url.
 *
 * @param text
 *            the text to be highlighted
 * @param url
 *            the link to apply to the text
 * @return an HTML link element
 * @requires |text| > 0
 * @ensures [HTML link is generated in the form <a href="url">text</a>]
 */
private static String generateLink(String text, String url) {
        assert text != null : "Violation of: text is not null";
        assert url != null : "Violation of: url is not null";
        assert text.length() > 0 : "Violation of: text is not empty";
        String link = String.format("<a href=\"%s\">%s</a>", url, text);
        return link;
}

Eh bien, en fait, il y a beaucoup de choses que je ne fais généralement pas ici; c'était pour un cours qui reposait fortement sur la conception par contrat. Cela dit, j'aime diviser le code en méthodes autant que possible. Ensuite, je documente uniquement les méthodes à l'aide de commentaires qui peuvent être convertis en une API comme Javadoc. En d'autres termes, j'évite autant que possible les commentaires en ligne. Après tout, ce sont les commentaires les moins susceptibles d'être mis à jour.

Bien sûr, je préfère rester dans le royaume de Python où le code est un peu plus lisible par défaut. Peut-être que dans cet espace, je n'ai pas besoin d'autant de commentaires. Voici un exemple de ce à quoi cela ressemble généralement :

def get_clean_data(tables: dict) -> pd.DataFrame:
    """
    Assigns appropriate types to columns. For example, this method
    converts the timestamp column to the appropriate Python data type
    datetime.

    :param tables: a raw dictionary of iMotions data for a participant
    :return: a pandas DataFrame of the iMotions data
    """
    data_table = tables[DATA]
    header = data_table[0]
    data = pd.DataFrame(data_table[1:], columns=header)
    data[TIMESTAMP] = pd.to_datetime(data[TIMESTAMP], format=TIME_FORMAT)
    data[FIXATION_SEQUENCE] = pd.to_numeric(data[FIXATION_SEQUENCE])
    data[FIXATION_DURATION] = pd.to_numeric(data[FIXATION_DURATION])
    return data

En fin de compte, je ne suis pas ici pour défendre ma position. Au lieu de cela, j'ai pensé qu'il serait plus intéressant de tracer ma trajectoire, de partager une partie de mon code et de parler de ce que notre communauté pense être la meilleure façon de gérer les commentaires. Dans la section suivante, nous expliquerons pourquoi je pense qu'il est important d'explorer les croyances dans la communauté technologique.

Croyances dans la communauté technologique

L'une des choses que j'aime dans ce domaine est la diversité des croyances que les gens ont autour d'aspects particuliers de la programmation. Par exemple, tout le monde dans ce domaine a un langage de programmation préféré ou un outil de développement préféré.

Naturellement, ces préférences sont enracinées dans les croyances concernant les avantages et les implications d'un langage ou d'un outil particulier. Par exemple, je préconise l'utilisation du contrôle de version parce que je crois qu'il aide les développeurs à restaurer les logiciels lorsqu'un bogue majeur est publié, parmi une douzaine d'autres avantages.

Malheureusement, ces croyances ne sont pas toujours ancrées dans la réalité. En fait, de nombreux développeurs ont des croyances basées sur des expériences, des rumeurs et une idéologie. Cela ne rend pas leurs croyances invalides; cela signifie simplement qu'ils sont peu enracinés dans la recherche scientifique.

Par exemple, dans le passé, j'ai enseigné un cours où j'étais censé dire aux étudiants de ne jamais utiliser plus d'une instruction de retour dans une méthode. Quelle est la logique derrière cela ? Y a-t-il des avantages à suivre cette règle ? Ce sont des questions auxquelles je ne connais pas les réponses, mais je vous garantis que quiconque lit ceci a sa propre opinion sur la question.

C'est fondamentalement le problème, non? Notre domaine est devenu tribal dans la façon dont les gens forment des factions autour de ces différentes croyances. Vous trouverez des gens qui jurent que le code de commentaire n'est pas seulement une bonne idée, il devrait être fait sur presque toutes les lignes. D'un autre côté, vous trouverez des gens qui croient que le code devrait être strictement auto-documenté; pas un commentaire en vue.

Bien sûr, ces croyances correspondent probablement davantage à un spectre, car chacun a ses propres opinions. Par exemple, j'ai lu que les commentaires ne devraient expliquer que le "pourquoi" et jamais le "quoi" ou le "comment". Alternativement, certaines personnes, comme moi, préfèrent limiter les commentaires à la documentation de l'API uniquement.

Avec toutes ces croyances qui flottent, comment quelqu'un peut-il donner un sens à tout cela. Eh bien, j'ai pensé que je prendrais un peu de temps pour au moins condenser certaines des croyances que j'ai vues sur Internet, afin que vous puissiez faire un choix éclairé par vous-même.

Dans la section suivante, nous commencerons à décomposer les différents types de croyances en matière de commentaires.

Croyances autour du code de commentaire

Lorsqu'il s'agit de résumer les croyances des membres de la communauté, j'ai dû proposer quelques catégories de croyances. Il y avait probablement une douzaine de façons de procéder, mais j'ai opté pour des catégories liées à la quantité de commentaires qui semblent appropriées, allant des positions qui préconisent le moins de commentaires aux positions qui préconisent le plus de commentaires. Cela dit, allons-y !

La conviction que les commentaires doivent être utilisés en dernier recours

Pour lancer cette liste, j'ai pensé que je partagerais quelques réflexions de la communauté sur la conviction que j'ai :les commentaires doivent être utilisés en dernier recours. Cela semble être la croyance la plus populaire, du moins selon les différentes recherches Google que j'ai effectuées.

Lorsque je cherchais des personnes partageant cette conviction, j'ai commencé par utiliser le terme de recherche "commenter le code est mauvais", ce qui m'a conduit à un article de Jeff Atwood.

Maintenant, j'hésite à partager une ressource de Jeff car je pense qu'il a eu un impact négatif durable sur notre communauté avec la création de StackOverflow. En fait, mon site Web est en grande partie une tentative de surclasser StackOverflow dans certains termes de recherche, afin que les gens puissent trouver un contenu plus compatissant.

Cela dit, je pense que Jeff avait une tonne de bonnes choses à dire dans cet article. Par exemple, j'ai beaucoup aimé le paragraphe suivant :

Bien que les commentaires ne soient ni bons ni mauvais en soi, ils sont fréquemment utilisés comme béquille. Vous devez toujours écrire votre code comme si les commentaires n'existaient pas. Cela force à vous d'écrire votre code de la manière la plus simple, la plus claire et la plus auto-documentée que vous puissiez trouver humainement.

Coding Without Comments par Jeff Atwood (24 juillet 2008)

Sans surprise, Jeff n'est pas le seul à avoir cette conviction. En fait, un article similaire de Peter Vogel est apparu pour la même requête. Dans cet article, Peter avance l'argument suivant :

Sur la base de ces trois faits, mon affirmation est simple :votre code va communiquer avec l'ordinateur et devrait également communiquer avec celui qui maintient le code (qui peut être vous, dans trois mois). Pour faciliter la vie du prochain développeur, le code doit être écrit et réécrit pour être aussi évident que possible. Ce qui reste aux commentaires, c'est d'expliquer ce à quoi le compilateur n'a pas accès :pourquoi le code est là. Ajouter des commentaires pour expliquer comment votre code fait son travail - ce que (je pense) certains lecteurs recommandaient - n'est pas la solution. Cela ne fait qu'augmenter les coûts.

Aucun commentaire :pourquoi commenter le code est toujours une mauvaise idée par Peter Vogel (13 juillet 2013)

Encore une fois, l'argument n'est pas que les commentaires sont intrinsèquement mauvais. Au lieu de cela, c'est que les commentaires ont un coût et qu'ils ne doivent être utilisés que lorsqu'ils ont du sens (c'est-à-dire pour expliquer pourquoi le code est là).

La conviction que les commentaires doivent signaler l'intention

Peut-être que la prochaine étape de l'exploitation des commentaires en dernier recours consiste à comprendre que le code ne peut jamais s'auto-documenter. Par conséquent, les commentaires doivent être utilisés pour signaler l'intention. Cette idéologie particulière vient de Jason McDonald, un habitué de la communauté Python, dans son article intitulé « To Comment of Not To Comment ». Dans cet article, il réfute explicitement trois arguments communs qui viennent de gens comme moi qui commentent en dernier recours :

• Les commentaires deviennent obsolètes
• Les commentaires créent du bruit de ligne
• Les commentaires prennent du temps

Au lieu de cela, Jason préconise une forme de commentaire de code plus empathique dans laquelle il énonce explicitement les points suivants :

– Tout commentaire doit décrire ce que vous intentionnez l'objectif ou le résultat d'une section de code à être. Cela est vrai, quelle que soit la fréquence ou la densité de vos commentaires. Les commentaires ne doivent jamais redire la fonctionnalité du code.

– Je pense qu'un bon test décisif consiste à imaginer supprimer tout sauf les commentaires. Avez-vous suffisamment d'informations pour réécrire complètement le programme ? De plus, les commentaires sont-ils indépendants de la langue et seraient-ils tout aussi utiles si vous passiez, par exemple, de Python à Java ?

To Comment or Not to Comment par Jason McDonald (20 janvier 2019)

Je pense que l'un des arguments les plus convaincants contre mon style personnel est que le code ne s'auto-documente pas. Par conséquent, si le code sans commentaire contient des bogues, comment le lecteur est-il censé savoir que ce n'est pas l'intention ? Il semble que le cadre "Commenting Showing Intent" résout ce problème.

La conviction que les commentaires doivent être utilisés librement

Si nous poussons le cadre de Jason un peu plus loin, nous trouverons où j'en étais lorsque j'ai appris à coder pour la première fois :les commentaires étaient partout. Dans cette idéologie, les commentaires doivent être utilisés aussi souvent que possible non seulement pour signaler l'intention, mais pour expliquer ce que fait le code.

Le premier endroit où j'ai vu cela préconisé était par un auteur nommé B.J. Keeton qui a partagé les principes suivants pour commenter :

– Soyez bref

– Gardez-les pertinents

– Utilisez-les généreusement, mais sans excès

Comment commenter votre code comme un pro :bonnes pratiques et bonnes habitudes par B.J. Keeton (3 avril 2019)

Il s'avère qu'il s'agit en fait d'une croyance assez courante dans la communauté. Je soupçonne que c'est parce que les développeurs ont une longue histoire de pas commentant leur code, alors les éducateurs et les autres personnes qui en avaient marre ont commencé à pousser pour de grandes quantités de commentaires.

Un autre auteur, Eric Jeker, soulève d'excellents points pour la foule des "commentaires généreusement". Premièrement, il soutient que les développeurs de niveau intermédiaire ont probablement une position similaire à la mienne parce qu'ils considèrent les commentaires comme une pratique pour les débutants. J'ai tendance à être d'accord avec lui ici. La technologie a beaucoup de problèmes culturels, donc l'élitisme motive probablement un peu la position "sans commentaire".

Deuxièmement, il parle beaucoup de la perte de temps et de la façon dont les commentaires peuvent s'intégrer dans un flux de travail qui vous fait gagner du temps. En particulier, j'aime ce passage :

Personnellement, j'aime ajouter des commentaires dans mon code car cela me facilite tellement la vie lorsque je reviens à d'anciennes applications que j'ai écrites dans le passé. Je déteste quand je ne commente pas un code, et je perds du temps à le comprendre à nouveau, c'est pourquoi c'est devenu un réflexe pour moi d'écrire des commentaires en premier lieu.

Parfois, j'implémente même ce que j'appelle CDD (Comment Driven Development), notamment lorsque je dois écrire un algorithme complexe. J'aime d'abord le décomposer en petites parties, sans me soucier de la syntaxe. J'écris ceci dans mes commentaires, puis je les "traduis" dans la langue que j'écris actuellement. Quand j'ai fini, je nettoie les inutiles.

Code de commentaire :nécessité ou redondance ? par Eric Jeker (17 août 2020)

Dans l'ensemble, l'argument autour des commentaires libéraux semble être qu'ils n'affectent pas l'exécution du code et peuvent être modifiés ou supprimés selon les besoins. En d'autres termes, ils ne font de mal à personne :une position qui va à l'encontre de la première position dont nous avons discuté.

Réviser mon style de commentaire personnel

Dans les trois catégories ci-dessus, je les ai en quelque sorte positionnées comme minimales, moyennes et maximales. Cela dit, il existe probablement des dizaines de façons différentes d'aborder les commentaires. En fait, après avoir écrit cet article, je pense que je veux prendre un peu de temps pour réviser un peu ma position.

Tout d'abord, j'adhère toujours à l'idée que moins de commentaires, c'est mieux. Je ne suis pas d'accord que les commentaires sont entièrement inoffensifs pour de nombreuses raisons qui ont été discutées tout au long. Par exemple, les commentaires peuvent devenir obsolètes ou transmettre des informations dénuées de sens ou cryptées qui font perdre plus de temps.

Cela dit, j'aime bien le modèle d'intention de Jason qui se concentre sur la rédaction de bons commentaires. Je ne sais pas si sa position diffère entièrement de la mienne, mais à tout le moins, il semble fournir un cadre qui permet d'éliminer certains des inconvénients que j'ai mentionnés ci-dessus.

Si je retiens quelque chose de cela, ce sera probablement la langue que j'utilise lors de la création de commentaires. Quand j'ai appris à écrire des commentaires, on ne m'a pas vraiment dit quoi écrire, juste que je devais écrire quelque chose. Beaucoup de personnes auxquelles j'ai fait référence dans cet article semblent avoir des stratégies décentes liées à la rédaction de commentaires.

Dans l'ensemble, je vais probablement éviter les commentaires moins souvent si cela signifie soutenir les gens qui finissent par lire mon code. En fin de compte, je veux m'assurer que je suis conscient des besoins des personnes avec qui je travaille. C'est la chose compatissante à faire.

Cela dit, c'est tout ce que j'ai pour aujourd'hui. C'est un peu différent de ce que j'écris habituellement. Si vous l'avez aimé, j'essaierai de faire plus de contenu comme celui-ci. Sinon, pas de soucis ! Assurez-vous simplement de me le faire savoir sur Discord ou Patreon que vous pouvez trouver ici. Sinon, faites attention !