Comment écrire efficacement du code maintenable ?

N'est-il pas intéressant de trouver un commentaire mal placé et inutile dans le code ?

Comment pouvez-vous écrire très peu de commentaires tout en gardant le code facile à comprendre ?

Une méthode majeure consiste à rendre le code auto-documenté. Lorsque le code est auto-documenté, il n'est pas nécessaire d'avoir des commentaires pour expliquer sa fonction ou son objectif, et cela rend aussi le code très facile à maintenir.

Dans cet article, je vais fournir quelques moyens de rendre votre code auto-documenté. Voici trois méthodes de base pour rendre le code auto-documenté :

Nommage : Utilisez des noms pour expliquer le but des variables, des fonctions, etc.
Encapsulation de fonctions : Encapsulez le code ayant une fonctionnalité spécifique dans une fonction pour clarifier son objectif.
Introduction de variables : Placez les expressions dans des variables dédiées.

Cela peut sembler simple, mais en pratique, cela peut être un peu délicat. Tout d'abord, vous devez comprendre où se situent les problèmes et où ces méthodes s'appliquent.

De plus, outre les trois ci-dessus, il existe d'autres approches plus largement appliquées :

Interfaces de classes et de modules : Exposez les fonctions dans des classes et des modules pour rendre le code plus clair.
Regroupement de code : Utilisez des groupes pour distinguer différents segments de code.

Ensuite, nous utiliserons des exemples pour discuter spécifiquement de la manière d'appliquer les 5 méthodes ci-dessus dans un usage pratique.

1. Nommage

Tout d'abord, regardez quelques exemples de la façon dont le code devient clair et auto-documenté lorsque le nommage est utilisé.

1. Renommage de fonctions

Nommer des fonctions n'est pas très difficile ; vous pouvez suivre ces règles :

Évitez les mots vagues tels que 'handle' ou 'manage' — handleLinks, manageObjects.
Utilisez des verbes actifs — cutGrass, sendFile — pour indiquer que la fonction effectue activement une action.
Spécifiez le type de valeur de retour — getMagicBullet, READFILE. Les langages fortement typés peuvent également utiliser des identificateurs de type pour indiquer le type de retour de la fonction.

2. Renommer les variables

Spécifiez les unités — s’il y a des paramètres numériques, vous pouvez ajouter leurs unités. Par exemple, utilisez widthPx au lieu de width pour préciser que l’unité de width est le pixel.
N’utilisez pas de raccourcis — a et b ne doivent pas être utilisés comme noms de paramètres.

2. Encapsulation des fonctions

Ensuite, regardez quelques exemples de la façon d’encapsuler du code dans des fonctions. Un avantage de l’encapsulation de fonctions est d’éviter la répétition de code, ou d’améliorer la structure du code.

1. Encapsuler le code dans des fonctions

C’est le plus élémentaire : encapsulez du code dans une fonction pour clarifier son objectif. Devinez ce que fait la ligne de code suivante :

var width = (value - 0.5) * 16;

Ce n’est peut-être pas très clair ; bien sûr, avec un commentaire, ce serait parfaitement clair, mais nous pouvons simplement l’encapsuler dans une fonction pour obtenir une auto-documentation...

var width = emToPixels(value);
 
function emToPixels(ems) {
    return (ems - 0.5) * 16;
}

Le seul changement est que le processus de calcul a été déplacé dans une fonction. Le nom de la fonction exprime clairement ce qu’elle fait, donc il n’est pas nécessaire d’écrire des commentaires. De plus, si nécessaire plus tard, cette fonction peut être appelée directement, ce qui fait d’une pierre deux coups et réduit le travail redondant.

2. Remplacer les expressions conditionnelles par des fonctions

Les instructions if contenant plusieurs opérandes sont plus difficiles à comprendre sans commentaires.

if(!el.offsetWidth || !el.offsetHeight) {
}

Savez-vous quel est le but du code ci-dessus ?

function isVisible(el) {
    return el.offsetWidth && el.offsetHeight;
}
 
if(!isVisible(el)) {
}

3. Introduction des variables

Enfin, parlons de la manière d'introduire des variables. Comparée aux deux méthodes ci-dessus, celle-ci peut être moins utile, mais dans tous les cas, la connaître vaut mieux que de ne pas la connaître.

1. Remplacer les expressions par des variables

Regardez cet exemple

if(!el.offsetWidth || !el.offsetHeight) {
}

Cette fois, au lieu de l'encapsuler dans une fonction, remplacez-le en introduisant des variables.

var isVisible = el.offsetWidth && el.offsetHeight;
if(!isVisible) {
}

2. Utiliser des variables à la place des équations

Nous pouvons également l'utiliser pour expliquer clairement des formules complexes :

return a * b + (c / d);

Remplacez-les par des variables.

var divisor = c / d;
var multiplier = a * b;
return multiplier + divisor;

4. Interfaces de classes et de modules

Les interfaces des classes et des modules — c'est-à-dire les méthodes et propriétés publiques — ressemblent un peu à une documentation expliquant comment les utiliser.

Regardez l'exemple suivant :

class Box {
    public function setState(state) {
        this.state = state;
    }
 
    public function getState() {
        return this.state;
    }
}

Cette classe pourrait également contenir d'autre code. J'ai délibérément choisi cet exemple pour illustrer comment l'interface publique peut être auto-documentée.

Pouvez-vous dire comment cette classe est appelée ? De toute évidence, ce n'est pas évident.

Ces deux fonctions devraient recevoir des noms raisonnables pour exprimer leur objectif. Mais même si c'est fait, nous ne savons toujours pas très bien comment les utiliser. Il faut alors lire davantage de code ou consulter la documentation.

Mais que se passerait-il si nous le changions comme ceci...

class Box {
    public function open() {
        this.state = open;
    }
 
    public function close() {
        this.state = closed;
    }
 
    public function isOpen() {
        return this.state == open;
    }
}

N'est-ce pas beaucoup plus clair ? Remarque : nous avons seulement changé l'interface publique ; sa représentation interne est la même que l'état this.state d'origine.

5. Regroupement du code

Utiliser des groupes pour distinguer différents segments de code est aussi une forme d'auto-documentation. Par exemple, comme indiqué dans cet article, nous devrions définir les variables aussi près que possible de leur lieu d'utilisation et classer les variables autant que possible. Cela peut aussi servir à préciser les relations entre différents groupes de code, ce qui permet aux autres de savoir plus facilement quels groupes de code ils doivent encore comprendre.

Regardez l'exemple suivant :

var foo = 1;
 
blah()
xyz();
 
bar(foo);
baz(1337);
quux(foo);

Comparé à ce qui suit :

var foo = 1;
bar(foo);
quux(foo);
 
blah()
xyz();
 
baz(1337);

Regroupez toutes les utilisations de foo ensemble, et vous pouvez voir les relations en un coup d'œil. Mais parfois, nous devons appeler d'autres fonctions entre les deux. Donc, si possible, essayez d'utiliser le regroupement de code ; sinon, ne forcez pas.

6. Autres suggestions

N'utilisez pas de marqueurs étranges ; les deux suivants sont équivalents

imTricky && doMagic();

if(imTricky) {
    doMagic();
}

De toute évidence, le dernier est meilleur. Les astuces syntaxiques n'apportent aucun bénéfice.

Nommez les constantes : s'il y a des valeurs spéciales dans le code, il est préférable de les nommer. var PURPOSE_OF_LIFE = 42;
Établissez des règles : il est préférable de suivre des règles de nommage cohérentes. Ainsi, les lecteurs peuvent deviner correctement la signification de diverses choses en se référant à d'autres codes.

Source : http://www.ido321.com/1360.html