La compréhension commence par des noms expressifs

En 2018, j’ai rejoint un grand projet à mi-parcours de son développement. Les ingénieurs d’origine avaient disparu, laissant derrière eux un code alambiqué et non documenté. Travailler avec ce type de code est difficile car on ne peut pas différencier la plomberie du domaine métier. Cela rend le débogage difficile et les modifications imprévisibles car on ne connaît pas l’impact. C’est comme essayer d’éditer un livre sans comprendre les mots.

De nombreux ingénieurs croient que la mesure du succès est quand le code compile. Je crois que c’est quand un autre ingénieur (ou vous dans six mois) comprend le « pourquoi » de votre code. Les ingénieurs d’origine ont handicapé les futurs ingénieurs en ne documentant pas et en utilisant des noms obscurs. Les noms sont parfois la seule fenêtre sur le processus de réflexion de l’ingénieur précédent.

Donald Knuth a dit avec justesse :

Les programmes sont destinés à être lus par des humains et seulement accessoirement à être exécutés par des ordinateurs. – Donald Knuth

Nommage

Le nommage est difficile car il nécessite d’étiqueter et de définir où et comment une pièce s’intègre dans une application.

Phil Karlton, alors chez Netscape, a observé :

Il n’y a que deux choses difficiles en informatique : l’invalidation du cache et le nommage des choses.
— Phil Karlton

Nous voyons notre code à travers le prisme des mots et des noms que nous utilisons. Les noms créent un langage pour que le prochain ingénieur comprenne. Ce langage peint un tableau de la façon dont l’auteur a comblé le fossé entre le domaine métier et le langage de programmation.

Ludwig Wittgenstein, un philosophe de la première moitié du 20e siècle, a dit :

Les limites de mon langage signifient les limites de mon monde. – Ludwig Wittgenstein

Le langage de notre logiciel n’est aussi descriptif que les noms que nous utilisons, et l’utilisation de noms vagues brouille l’objectif du logiciel ; l’utilisation de noms descriptifs apporte de la clarté et de la compréhension.

Imaginez visiter un pays où vous ne parlez pas la langue. Une simple demande comme demander à utiliser les toilettes provoque des regards perplexes. L’incapacité à communiquer est frustrante, voire effrayante. Un ingénieur ressent la même chose face à des noms confus, peu clairs ou pire encore, trompeurs.

Ce sentiment est mieux expérimenté.

Expérience

Examinez le premier extrait de code, que fait ce code ? Quel est le pourquoi ?

Prenez votre temps.

public class StringHelper
{
    public string Get(string input1, string input2)
    {
        var result = string.Emtpy;
        if(!string.IsNullOrEmtpy(input1) && !string.IsNullOrEmtpy(input2))
        {
            result = $"{input1} {input2}";
        }
        return result;
    }
}

Le code ci-dessus est une simple concaténation de deux chaînes. Ce que le code ne vous dit pas, c’est le « pourquoi ». Le « pourquoi » est si important que sans lui, il est difficile de modifier le comportement sans comprendre l’impact. Bien sûr, enquêter sur l’utilisation du code révélera probablement son « pourquoi », mais c’est justement le point. Vous ne devriez pas avoir à découvrir l’objectif du code, au lieu de cela, l’auteur aurait dû laisser des indices, c’est sa responsabilité de le faire.

Revisitez le code, mais avec un peu de « pourquoi » saupoudré dedans.

Encore une fois, prenez votre temps, observez la différence que vous ressentez en lisant ce code.

    public class FirstAndLastNameFormatter
    {
        public string Concatenate(string firstName, string lastName)
        {
            var fullName = string.Emtpy;
            if(!string.IsNullOrEmtpy(firstName) && !string.IsNullOrEmtpy(lastName))
            {
                fullName = $"{firstName} {lastName}";
            }
            return fullName;
        }
    }

Le « pourquoi » donne vie au code, il y a une histoire à lire.

Communiquer

Communiquer l’intention et la conception au prochain ingénieur permet au logiciel de vivre et de croître car si les ingénieurs ne peuvent pas modifier le logiciel, il meurt. C’est une tragédie, d’autant plus quand c’est le résultat d’une mauvaise conception et d’un manque d’expressivité — chacun est évitable avec les connaissances.

Rendez service au prochain ingénieur et soyez expressif dans votre code. Utilisez des noms descriptifs et capturez le « pourquoi » car qui sait, le prochain ingénieur pourrait être vous.