L'auteur du matériel, dont nous publions la traduction aujourd'hui, dit qu'elle est obsédée par l'écriture de code propre. Elle estime que le code devrait être écrit de telle sorte que, d'une part, à l'avenir, il serait pratique pour d'autres programmeurs de travailler avec lui, y compris son auteur, et d'autre part, en tenant compte de la possibilité d'étendre ce code. Autrement dit, nous devons nous efforcer de faciliter l'ajout de nouvelles fonctionnalités à l'application et de faciliter la maintenance de sa base de code. Si les programmes ont été écrits en tenant compte uniquement des besoins des ordinateurs, alors les programmeurs pourraient probablement exprimer leurs pensées uniquement à l'aide de zéros et de uns, sans se soucier de rien d'autre. Cet article fournit quelques directives pour l'écriture de code de qualité, illustrées par des exemples JavaScript.
1. Utilisez des noms de variables et de fonctions conviviaux
Le code est beaucoup plus facile à lire lorsqu'il est écrit à l'aide de noms clairs et descriptifs de fonctions et de variables. Voici le code qui n'est pas très clair:
function avg (a) { let s = a.reduce((x, y) => x + y) return s / a.length }
Sa lisibilité s'améliorera considérablement si vous utilisez les noms conviviaux de variables et de fonctions qui reflètent leur signification.
function averageArray (array) { let sum = array.reduce((number, currentSum) => number + currentSum) return sum / array.length }
Ne vous efforcez pas de minimalisme lors de l'écriture de textes de programme. Utilisez des noms de variables complets que toute personne qui utilisera votre code à l'avenir pourra facilement comprendre.
2. Écrivez de courtes fonctions qui résolvent un problème
Les fonctions sont plus faciles à maintenir, elles deviennent beaucoup plus compréhensibles, lisibles si elles visent à résoudre un seul problème. Si nous rencontrons une erreur, alors, lors de l'utilisation de petites fonctions, il devient beaucoup plus facile de trouver la source de cette erreur. De plus, les capacités de réutilisation du code sont améliorées. Par exemple, la fonction ci-dessus pourrait être appelée
sumAndAverageArray , car nous y calculons la somme des valeurs des éléments du tableau à l'aide de la méthode de
reduce , puis nous trouvons la valeur moyenne, en divisant le montant résultant par le nombre d'éléments du tableau. Voici la fonction.
function sumAndAverageArray(array) { let sum = array.reduce((number, currentSum) => number + currentSum) return sum / array.length }
Il peut être divisé en deux fonctions, puis le rôle de chaque morceau de code deviendra plus compréhensible. De plus, si nous créons un grand programme, la présence de la fonction
sumArray peut être très utile. Voici le code de deux nouvelles fonctionnalités. L'un calcule la somme des éléments du tableau, le second renvoie leur valeur moyenne.
function sumArray(array) { return array.reduce((number, currentSum) => number + currentSum) } function averageArray(array) { return sumArray(array) / array.length }
Un signe que la fonction peut être divisée en deux est la possibilité d'utiliser le mot «et» dans son nom.
3. Documentez le code
Écrivez une bonne documentation pour votre code - alors quelqu'un qui le rencontrera à l'avenir comprendra ce qui est fait dans ce code et pourquoi. Voici un exemple de fonction défaillante. Certains «nombres magiques» sont utilisés ici, leur signification n'est expliquée nulle part.
function areaOfCircle (radius) { return 3.14 * radius ** 2 }
Vous pouvez ajouter des commentaires ici pour rendre ce code plus compréhensible pour quelqu'un qui ne connaît pas la formule de calcul de l'aire d'un cercle.
const PI = 3.14 // , function areaOfCircle (radius) { // : // return PI * radius ** 2 }
Ce code n'est qu'un exemple. Probablement, dans cette situation, au lieu d'introduire votre propre constante stockant le nombre Pi, il serait préférable d'utiliser la propriété
Math.PI standard.
Les commentaires sur le code devraient répondre à la question «pourquoi».
Veuillez noter que pour documenter du code, il est judicieux d'utiliser des outils spéciaux et les règles de commentaire de code correspondantes. Lorsqu'il est appliqué à Python, j'aime
Google Style Docstrings , lorsqu'il est appliqué à JavaScript, j'aime
JSDoc .
4. Pensez à utiliser les règles de Sandy Metz
Sandy Metz est une excellente programmeuse Ruby, fait des présentations intéressantes et écrit des livres. Elle a formulé quatre règles pour écrire du code propre dans des langages orientés objet. Les voici.
- Les classes ne doivent pas dépasser 100 lignes de code.
- Les méthodes et fonctions ne doivent pas dépasser 5 lignes de code.
- Les méthodes ne doivent pas passer plus de 4 paramètres.
- Les contrôleurs ne peuvent initialiser qu'un seul objet.
Je recommande de regarder sa
performance concernant ces règles.
Cela fait maintenant environ deux ans que je respecte ces règles et elles sont tellement ancrées dans mon esprit que je les respecte littéralement «sur la machine». Je les aime et je crois que leur utilisation augmente la commodité de maintenir le code.
Veuillez noter que ces règles ne sont que des recommandations, mais leur utilisation améliorera considérablement votre code.
5. Appliquer les règles sélectionnées séquentiellement
L'application cohérente des règles d'écriture du code est très importante, que vous écriviez le code d'un projet vous-même ou que vous travailliez en équipe. En particulier, cela s'exprime dans le fait que quiconque lit du code résultant du développement d'une équipe doit le percevoir dans son ensemble. Avec cette approche, la paternité de lignes de code individuelles ne peut être établie qu'en contactant Git. Si vous, en JavaScript, utilisez un point-virgule - placez-le où vous en avez besoin. La même chose s'applique aux guillemets - sélectionnez des guillemets doubles ou simples et, s'il n'y a pas de bonne raison, utilisez toujours ce que vous choisissez.
Je recommande d'appliquer le guide de style de code et le linter, qui vous permettent d'amener le code à la norme sélectionnée. Par exemple, pour JavaScript j'aime les règles de
Standard JS , pour Python j'aime les règles de
PEP8 .
En fait, l'essentiel ici est de trouver les règles de conception de code et de les respecter.
6. N'oubliez pas le principe SEC
L'une des premières idées que les gens essaient de transmettre à quelqu'un qui veut devenir programmeur est: «Ne vous répétez pas, SEC». Si vous remarquez des fragments en double dans vos projets, utilisez des constructions logicielles qui réduiront les répétitions du même code. Je conseille souvent à mes élèves de jouer au jeu
SET afin d'améliorer leurs compétences en reconnaissance de formes.
Cependant, si vous décidez d'appliquer fanatiquement le principe DRY ou décidez d'abstraire les modèles mal sélectionnés, la lisibilité du code peut sérieusement se détériorer et, plus tard, vous devrez peut-être recourir à la création de copies des mêmes constructions plus souvent. Soit dit en passant, Sandy Metz a un excellent article sur la façon dont la duplication de code est moins mauvaise qu'une
abstraction ratée .
Par conséquent, cela ne vaut pas la peine d'être répété, mais cela ne vaut pas non plus la peine, dans la lutte pour observer le principe DRY, de modifier le code à un point tel qu'il peut devenir difficile à comprendre.
7. Utilisez les idées d'encapsulation et de modularité.
Regroupez les variables et fonctions associées afin de rendre votre code plus facile à comprendre et à l'améliorer en termes de réutilisation. Voici un exemple de code peu bien organisé, dans lequel les informations sur une personne sont présentées sous forme de variables distinctes.
let name = 'Ali' let age = 24 let job = 'Software Engineer' let getBio = (name, age, job) => `${name} is a ${age} year-old ${job}`
Si dans un tel programme, il est nécessaire de traiter les données de nombreuses personnes, il serait préférable d'utiliser quelque chose comme la construction suivante.
class Person { constructor (name, age, job) { this.name = name this.age = age this.job = job } getBio () { return `${this.name} is a ${this.age} year-old ${this.job}` } }
Et si le programme doit fonctionner uniquement avec des données sur une personne, elles peuvent être organisées comme indiqué ci-dessous.
const ali = { name: 'Ali', age: 24, job: 'Software Engineer', getBio: function () { return `${this.name} is a ${this.age} year-old ${this.job}` } }
De la même manière, on devrait envisager de diviser les programmes longs en modules, dans des fichiers séparés. Cela facilitera l'utilisation du code alloué dans des fichiers séparés dans différents projets. Dans les fichiers volumineux avec le code du programme, il est souvent difficile de naviguer et les petits modules compréhensibles sont faciles à utiliser dans le projet pour lequel ils ont été créés et, si nécessaire, dans d'autres projets. Par conséquent, efforcez-vous d'écrire du code modulaire compréhensible en combinant des éléments liés de manière logique.
Résumé
Dans cet article, nous avons partagé avec vous quelques recommandations pour écrire du code propre et compréhensible. Cependant, ce ne sont que des recommandations. Ce sont des conseils pour vous aider à rédiger des textes de programme de qualité. Si vous appliquez systématiquement des règles similaires à celles décrites ici, alors, par rapport au code qui n'utilise pas quelque chose de similaire, le code écrit à l'aide de règles sera plus compréhensible, il sera plus facile de l'étendre, de le maintenir et de le réutiliser.
Chers lecteurs! Quelles règles suivez-vous pour votre code?
