Les mots «code auto-documenté» sont une autre façon de dire «code lisible». En soi, elle ne remplacera pas cette documentation ou ces bons commentaires , mais avec ou sans elle, elle vous facilitera certainement la vie et celle de vos collègues.
Examinons quelques principes importants pour la création de code auto-documenté.
N'utilisez pas de "nombres magiques"
Dites-moi, que signifie cette ligne?
if (students.length > 23) {
Vérifie s'il y a plus d'étudiants que 23? Et qu'est-ce que cela signifie? Pourquoi exactement 23, et non, disons 24?
Un nombre magique est un nombre sans contexte. Vous devrez consacrer du temps et des efforts pour comprendre ce contexte. Débarrassez-vous des travaux inutiles, donnez immédiatement et explicitement au numéro la désignation:
const maxClassSize = 23; if (students.length > maxClassSize) {
Essayez de lire le code maintenant. Nous vérifions non pas «s'il y a plus d'étudiants que 23», mais «s'il y a plus d'étudiants que la classe n'en accueille».
Utilisez des noms clairs pour les variables
Je ne sais pas pourquoi, mais avant j'avais constamment peur de faire des noms de variables longs. Ce qui était stupide de ma part, car les rStuNms et fStuNms sont terribles par rapport à r awStudentNames et à FilterStudentNames .
Ces derniers semblent-ils encore longs? Pensez-y ensuite: après 2 semaines de vacances et en travaillant avec un autre code, vous oublierez une bonne moitié des abréviations. À savoir, la possibilité de lire des noms de variables en déplacement est la possibilité de lire du code à la volée:
const fStuNms = stus.map(s => sn)
Une autre bonne astuce consiste à utiliser des conventions (conventions de dénomination). Si la variable est booléenne, commencez son nom par is ou has ( isEnrolled: true ). Si la variable est un tableau, utilisez le pluriel ( élèves ). De nombreux nombres doivent commencer par min ou max . Et les noms de fonction doivent contenir un verbe, par exemple, createSchedule ou updateNickname . En parlant de fonctionnalités ...
Écrire de minuscules fonctions nommées
Les variables ne sont pas le seul moyen de lire le code. En tant que jeune programmeur, j'ai utilisé des fonctions uniquement pour éviter la duplication de code . La vraie révélation pour moi a été que, tout d'abord, il est logique de créer des fonctions pour décrire ce qui se passe .
Prenez quelques secondes pour regarder ce code et dire ce qu'il fait:
const handleSubmit = (event) => { event.preventDefault(); NoteAdapter.update(currentNote) .then(() => { setCurrentAlert('Saved!') setIsAlertVisible(true); setTimeout(() => setIsAlertVisible(false), 2000); }) .then(() => { if (hasTitleChanged) { context.setRefreshTitles(true); setHasTitleChanged(false); } }); };
Faites de même pour le code:
const showSaveAlertFor = (milliseconds) => () => { setCurrentAlert('Saved!') setIsAlertVisible(true); setTimeout( () => setIsAlertVisible(false), milliseconds, ); }; const updateTitleIfNew = () => { if (hasTitleChanged) { context.setRefreshTitles(true); setHasTitleChanged(false); } }; const handleSubmit = (event) => { event.preventDefault(); NoteAdapter.update(currentNote) .then(showSaveAlertFor(2000)) .then(updateTitleIfNew); };
Il semble qu'il y ait plus de caractères, mais combien plus lisible, non? Il suffisait de répartir les opérations logiques dans de petites fonctions nommées. De plus, les petites fonctions elles-mêmes ne sont pas nécessaires à lire dans la plupart des situations - ce sont des détails d'implémentation. Pour comprendre le code, il suffit de regarder la fonction la plus élevée, constituée d'une chaîne d'événements facilement compréhensibles.
Mais plus loin - plus, un peu plus tard, vous vous rendrez compte que ces petites fonctions sont très faciles à réutiliser. La réutilisabilité est une conséquence d'une meilleure lisibilité, et non l'inverse.
Ajoutez des descriptions de test utiles
Les tests auto-documentés sont probablement les moins évoqués, mais en vain.
Disons que nous avons une fonction comme celle-ci:
const getDailySchedule = (student, dayOfWeek) => {
Imaginez qu'il contient de nombreuses opérations différentes: il reçoit un programme pour un mois; si aujourd'hui est un jour de congé, renvoie un tableau vide; si l'étudiant est inscrit dans des classes supplémentaires, les ajoute en fin de journée, etc. En général, vous avez compris l'idée: la fonction est complexe et il serait bien d'écrire l'algorithme de son travail quelque part en mots simples.
Essayer de l'intégrer dans un commentaire est une mauvaise idée: un commentaire deviendra une fois obsolète et non le fait qu'il sera corrigé à temps. Savez-vous où l'enregistrement de l'algorithme d'opération est approprié? Dans les tests:
describe('getDailySchedule ', () => { it(" ", () => { it(' , ', () => { it(' ', () => {
C'est la façon la plus élégante de commenter le code sans commentaire dans le code.
Conclusion: la lisibilité est plus importante que l'intelligence
Tout le monde peut écrire du code compréhensible pour lui-même; un bon développeur écrit du code compréhensible pour les autres . Il est rare que quelque chose d'important soit créé par une seule personne, ce qui signifie que tôt ou tard d'autres personnes liront votre code. Mais même si vous êtes sûr que vous seul examinerez du code, considérez que vous, aujourd'hui et vous, dans un mois, êtes des personnes différentes en termes de capacité à se souvenir de ce code.