Geekly articles weekly

10 principes du code auto-documenté

Salut Aujourd'hui, je veux partager des conseils sur l'écriture d' un code parfait et compréhensible, tiré du livre de Peter Goodlif, «L'art d'un programmeur // La pratique de l'écriture d'un bon code».

Bien sûr, il serait bien de lire ce livre divertissant à tous ceux qui écrivent le code, mais pour ceux qui sont particulièrement paresseux, mais qui veulent cesser de tourmenter moins et tromper leurs collègues ( avoir une conscience ), je présente 10 principes d'auto-documentation du code sous cat :

1. Écrivez un code simple avec un bon formatage


Le format de présentation a un impact énorme sur la facilité de compréhension du code. Une représentation raisonnable transmet la structure du code: les fonctions, les boucles et les instructions conditionnelles deviennent plus claires.

int fibonacci(int position) { if (position < 2) { return 1; } int previousButOne = 1; int previous = 1; int answer = 2; for (int n = 2; n < position; ++n) { previousButOne = previous; previous = answer; answer = previous + previousButOne; } return answer; }

  • Assurez-vous que l'exécution normale de votre code est évidente. La gestion des erreurs ne doit pas nuire à la séquence d'exécution normale. Les constructions conditionnelles if-then-else doivent avoir un ordre de branche uniforme (par exemple, toujours placer la branche de code "régulière" avant la branche "gestion des erreurs", ou vice versa).
  • Évitez de nombreux niveaux d'instructions imbriquées. Sinon, le code devient compliqué et nécessite des explications détaillées. Il est généralement admis que chaque fonction ne devrait avoir qu'un seul point de sortie; c'est ce qu'on appelle le code d' entrée unique, de sortie unique (SESE, une entrée, une sortie) . Mais généralement, cette restriction rend la lecture du code difficile et augmente le nombre de niveaux d'imbrication. Je préfère l'option de fonction fibonacci ci-dessus que l' option de style SESE suivante:

     int fibonacci(int position) { int answer = 1; if (position >= 2) { int previousButOne = 1; int previous = 1; for (int n = 2; n < position; ++n) { previousButOne = previous; previous = answer; answer = previous + previousButOne; } } return answer; }

    Je refuserais une imbrication excessive en faveur de la déclaration de retour supplémentaire - il est devenu beaucoup plus difficile de lire la fonction. La pertinence de masquer le retour quelque part au fond de la fonction est très douteuse, mais les simples calculs abrégés à son début rendent la lecture très facile.
  • Méfiez-vous des optimisations de code qui provoquent la clarté de l'algorithme sous-jacent. Optimisez votre code uniquement lorsqu'il devient clair qu'il interfère avec des performances de programme acceptables. Lors de l'optimisation, faites des commentaires clairs concernant le fonctionnement de cette section de code.

2. Choisissez des noms significatifs


Les noms de toutes les variables, types, fichiers et fonctions doivent être significatifs et non trompeurs. Le nom doit décrire correctement ce que c'est. Si vous ne parvenez pas à trouver un nom significatif, alors vous ne savez pas si vous comprenez le fonctionnement de votre code.

Le système de dénomination doit être cohérent et ne pas provoquer de mauvaises surprises. Assurez-vous que la variable n'est toujours utilisée qu'aux fins suggérées par son nom.

Un bon choix de noms est probablement le meilleur moyen d'éviter les commentaires inutiles. Les noms sont le meilleur moyen de rapprocher le code de l'expressivité des langues naturelles.

3. Divisez le code en fonctions indépendantes


La façon dont vous divisez le code en fonctions et les noms que vous leur donnez peuvent rendre le code compréhensible ou complètement incompréhensible.

  • Une fonction, une action

Minimisez les effets secondaires inattendus, quelle que soit leur utilité. Ils auront besoin de documentation supplémentaire.
Écrivez des fonctions courtes. Ils sont plus faciles à comprendre. Vous pouvez naviguer dans un algorithme complexe s'il est divisé en petits fragments avec des noms significatifs, mais cela ne peut pas être fait dans la masse informe du code.

4. Choisissez des noms de type significatifs


Dans la mesure du possible, décrivez les limitations ou le comportement à l'aide des fonctionnalités linguistiques disponibles. Par exemple:

  • Lorsque vous déterminez une valeur qui ne changera pas, affectez-lui un type constant (utilisez const en C).
  • Si la variable ne doit pas prendre de valeurs négatives, utilisez un type non signé (s'il existe dans le langage).
  • Utilisez des énumérations pour décrire l'ensemble de données associé.
  • Choisissez correctement le type de variables. En C / C ++, écrivez size dans les variables de type size_t et les résultats des opérations arithmétiques avec des pointeurs sur les variables de type ptrdiff_t .

5. Utilisez des constantes nommées


Un code comme si (counter == 76) laisse perplexe. Quelle est la signification magique de 76? Quelle est la signification de ce chèque? La pratique des nombres magiques est vicieuse. Ils obscurcissent la signification du code. Il vaut mieux écrire comme ceci:

 const size_t bananas_per_cake = 76; ... if (count == bananas_per_cake) { //    }

Si le code constant 76 se trouve souvent dans le code (excusez-moi, bananas_per_cake ), un avantage supplémentaire est obtenu: quand il est nécessaire de changer le contenu des bananes dans la tarte, il suffit de modifier le code en un seul endroit, plutôt que d'effectuer une recherche / modification globale du nombre 76, ce qui est lourd d'erreurs.

Cela s'applique non seulement aux nombres, mais également aux chaînes constantes. Jetez un œil à tous les littéraux de votre code, surtout s'ils se produisent à plusieurs reprises. Ne serait-il pas préférable d'utiliser à la place des constantes nommées?

6. Mettez en évidence les morceaux de code importants


Essayez de mettre en évidence le code important dans le contexte du matériel ordinaire. Au bon endroit, vous devriez attirer l'attention du lecteur. Il existe plusieurs astuces pour cela. Par exemple:

  • Placez judicieusement les annonces dans la salle de classe. Tout d'abord, les informations sur les objets ouverts doivent être envoyées, car c'est l'utilisateur de la classe qui en a besoin. Les détails de mise en œuvre fermés doivent être placés à la fin, car ils sont moins intéressants pour la plupart des lecteurs.
  • Si possible, masquez toutes les informations non essentielles. Ne laissez pas de déchets inutiles dans l'espace de noms global. C ++ a l'idiome pimpl, qui vous permet de masquer les détails de l'implémentation de la classe. (Meyers 97).
  • Ne cachez pas le code important. N'écrivez pas plus d'une instruction sur une ligne et simplifiez cette instruction. Le langage vous permet d'écrire des instructions très ingénieuses de la boucle for, dans lesquelles toute la logique tient sur une seule ligne à l'aide de nombreuses virgules, mais de telles instructions sont difficiles à lire. Évitez-les.
  • Limitez la profondeur d'imbrication des instructions conditionnelles. Sinon, il est difficile de remarquer le traitement de cas vraiment importants derrière un tas de si et de parenthèses.

7. Combinez les données connexes


Toutes les informations connexes doivent être réunies au même endroit. Sinon, vous ferez non seulement sauter le lecteur à travers les cerceaux, mais vous rechercherez également ces cerceaux avec ESP. L'API de chaque composant doit être représentée par un seul fichier. S'il y a trop d'informations interconnectées pour être présentées au même endroit, cela vaut la peine de réviser l'architecture du code.

Si possible, combinez des objets à l'aide de constructions de langage. En C ++ et C #, vous pouvez combiner des éléments dans le même espace de noms . En Java, le moteur de package est un outil d'union. Les constantes associées peuvent être définies dans une énumération.

8. Étiqueter les fichiers


Placez un bloc de commentaires au début du fichier avec une description du contenu du fichier et du projet auquel il se rapporte. Cela ne nécessite pas beaucoup de travail, mais est très avantageux. Quiconque doit accompagner ce dossier aura une bonne idée de ce qu'il traite. Ce titre peut avoir une signification particulière: la plupart des éditeurs de logiciels, pour des raisons juridiques, exigent une déclaration de copyright dans chaque fichier source. En règle générale, les en-têtes de fichiers ressemblent à ceci:

 /********************************************************* * File: Foo.java * Purpose: Foo class implementation * Notice: (c) 1066 Foo industries. All rights reserved. ********************************************************/

9. Traitez correctement les erreurs


Mettez la gestion de toutes les erreurs dans le contexte le plus approprié. S'il y a un problème de lecture / écriture sur le disque, il doit être traité dans le code qui traite de l'accès au disque. Pour gérer cette erreur, vous devrez peut-être générer une autre erreur (telle qu'une exception «Je ne peux pas charger le fichier»), en la passant à un niveau supérieur. Cela signifie qu'à chaque niveau du programme, l'erreur doit être une description précise du problème dans son contexte . Cela n'a aucun sens de gérer l'erreur associée à une défaillance de disque dans le code d'interface utilisateur.

Le code d'auto-documentation aide le lecteur à comprendre où l'erreur s'est produite, ce qu'elle signifie et quelles sont ses conséquences pour le programme à l'heure actuelle.

10. Écrivez des commentaires significatifs


Nous avons donc essayé d'éviter d'écrire des commentaires en utilisant d'autres méthodes indirectes de documentation du code. Mais après avoir fait tous les efforts pour écrire du code compréhensible, tout le reste doit être fourni avec des commentaires. Pour rendre le code facile à comprendre, il doit être complété par une quantité appropriée de commentaires. Lequel?

Essayez d'abord d'autres astuces. Par exemple, vérifiez si vous pouvez rendre le code plus clair en modifiant le nom ou en créant une fonction d'aide, et évitez ainsi de commenter.


Je suis sûr qu’après l’introduction de plusieurs de ces principes dans l’habitude, vous rendrez un programmeur plus heureux. Et vous serez cet heureux programmeur. Quand? Au moment de retourner travailler sur son code il y a six mois.

Source: https://habr.com/ru/post/fr458264/

More articles:


All Articles