J’aime donner des conseils sur la façon d’écrire le meilleur code pour divers projets.
Lorsque les gens commencent à apprendre la programmation, c’est souvent la partie logique qui est fascinante et stimulante. Ce qui est souvent négligé, ce sont les aspects les plus nuancés de la programmation tels que le nommage des variables, la structure du code, la documentation, etc. Le but de cet article est d’introduire quelques conseils simples sur ces aspects qui sont faciles à mettre en œuvre et qui, espérons-le, vous feront écrire code meilleur et plus lisible.
Codez toujours comme si le gars qui finirait par maintenir votre code serait un psychopathe violent qui sait où vous vivez.
1. Écrire des fonctions descriptives et des noms de variables
De nombreux programmeurs débutants et professionnels ont parfois tendance à nommer leurs fonctions et variables avec des noms non descriptifs. Le matériel pédagogique disponible est en partie à blâmer ici. De nombreux tutoriels et livres introduisant des fonctions et des variables ne les nomment pas correctement, appelant les fonctions « f » et les variables « x » et « y » par exemple. L’un des aspects brillants d’avoir des noms pour les variables et les fonctions est que le programmeur peut transmettre des informations sur le rôle que joue cette variable ou cette fonction dans le programme. Une fonction appelée « f » ne nous donne aucune information sur ce qu’elle fait. Il en va de même pour « x » et « y ». Une autre occurrence courante (que l’on trouve aussi souvent dans le matériel pédagogique) est d’avoir des variables avec des « fluffs » inutiles dans le nom, telles que « mon_numéro » ou « la_réponse ». Qu’est-ce qui fait que le numéro appartient au programmeur ou que la réponse est la réponse?
Parfois, il est également très tentant de nommer vos variables dans le contexte du domaine du programme et non du domaine du problème, par exemple, en nommant vos paramètres de fonction « input » et votre valeur de retour « output » ou « return_value ». Cela ne donne aucune information utile que nous ne connaissons pas déjà. Bien sûr, les variables vues en premier juste après la déclaration d’une fonction sont des entrées. Même avec tout ce qui vient après une déclaration de retour, il doit s’agir d’une sortie.
Exemple de mauvais style de dénomination
def list_func(inputs): temp = 0 for input in inputs: temp += input output = temp return output
Au lieu de faire les erreurs ci-dessus, on peut utiliser la possibilité de nommer les choses pour transmettre le sens du programme à la place, en nommant les fonctions et les variables en relation avec le problème qu’elles essaient de résoudre.
Il est aussi parfois utile de mentionner les unités dans les noms de variables. Dans mon expérience personnelle, cela a été particulièrement utile avec des variables représentant le temps, par exemple, « ms_to_sleep », « hours_to_work », etc. Ne pas avoir une compréhension complète des unités utilisées peut, en fin de compte, être très coûteux.
Exemple de bonne dénomination de variable
def sum(nums): cur_sum = 0 for num in nums: cur_sum += num return cur_sum
Pendant que nous parlons de lisibilité, il existe une autre technique qui peut être utilisée pour améliorer le code, à savoir la suppression des commentaires. La plupart des codes sont trop commentés et vous vous demandez peut-être pourquoi c’est une mauvaise chose. Le problème est que les commentaires doivent être maintenus, tout comme le code. Mais le code casse ou montre notre comportement inattendu s’il est faux. Un commentaire, d’autre part, ne cassera pas le programme s’il est faux ou faux, conduisant à être trompeur au fil du temps.
Par conséquent, les commentaires peuvent être dangereux pour expliquer le code car ils ne sont responsables d’aucun de ses comportements. Heureusement, nous avons ce merveilleux outil pour expliquer ce que fait le code, à savoir le langage de programmation dans lequel nous programmons. Si nous écrivons du code lisible dans notre langage de programmation, nous ne devrions pas avoir besoin de commentaires car le code serait auto-descriptif. Chaque fois que vous ressentez le besoin d’écrire des commentaires sur ce que fait votre code, essayez de penser à une façon d’expliquer cela dans le code à la place, comme nommer les variables différemment ou extraire du code dans une fonction distincte.
Une règle générale consiste à commenter Pourquoi le code est tel qu’il est, non Quel c’est fait.
# A function that takes a list of numbers and outputs # the sum. def list_func(inputs): # We use temp to contain our sum temp = 0 # Loop over each number in the inputs for input in inputs: # Add our current number to our sum temp += input # Assign our final sum to the output output = temp # Return our output return output
Au lieu d’avoir chaque commentaire reflétant chaque ligne de code, il est beaucoup plus utile de mettre des commentaires là où l’on anticipe que les lecteurs du code seront confus, et de commenter Pourquoi le code est écrit tel quel.
def sum(nums): # Instead of writing our own function we could use # Python's inbuilt 'sum' function here but we want # to use this function as an example for an online # article. cur_sum = 0 for num in nums: cur_sum += num return cur_sum
3. Classes et fonctions de documents
La documentation des classes et des fonctions serait l’exception à la règle ci-dessus. Les commentaires sont en général inutiles, mais un endroit où ils ont leur utilité est de documenter des concepts de niveau supérieur. Parfois, vous ne pouvez pas faire correspondre pleinement ce qu’une fonction fait dans son nom sans taper une phrase entière, ce qui rend le nom de la fonction trop verbeux. Pour quelqu’un qui lit le code, il est très utile que les fonctions et les classes aient une documentation, soit sous forme de commentaires, soit sous forme de docstring. Cela fait gagner du temps au lecteur car il n’a pas à lire toute la fonction ou la classe pour comprendre ce qu’elle fait et quels sont ses paramètres et sa sortie.
Pour les langages à typage dynamique, cela est particulièrement important. Dans les langages à typage statique, les fonctions ont une signature qui spécifie quels doivent être ses types d’entrée et quel est le type de sortie. Ce n’est pas le cas dans les langages à typage dynamique où les types des paramètres ne sont pas explicitement donnés. Si la fonction n’est pas documentée, il faut généralement en lire au moins le début pour comprendre quelle « forme » les paramètres doivent avoir. Une bonne documentation de fonction qui spécifie les types de paramètres ainsi que la sortie, peut-être même avec un exemple, évite au lecteur d’avoir à comprendre cela et il peut plutôt faire confiance à la documentation. Le guide de style Python de Google en est un bon exemple.
4. Fonctions d’aide à l’écriture
Les fonctions sont probablement les plus connues pour éviter la duplication et la réutilisation du code, mais elles peuvent également être utilisées pour faciliter la lisibilité du code. En règle générale, avoir une fonction de longueur supérieure à la hauteur de votre écran le rend peu maniable et difficile à lire. Le lecteur devrait garder les variables du début de la fonction dans sa tête pendant qu’il lit le reste, et il est difficile d’avoir une bonne image du code. C’est là qu’interviennent les fonctions d’assistance. Habituellement, une grande fonction comme celle mentionnée ci-dessus aurait plusieurs « sections » de code où chaque section ferait quelque chose de légèrement différent du reste du code. Chacune de ces sections peut être transformée en une fonction d’assistance qui a un nom descriptif. Cela aiderait à la lisibilité de la grande fonction. Au lieu d’être long et lourd, il serait court et rapide avec des appels de fonction faciles à lire à la place.
5. Suivez les conventions du code
En tant que programmeur débutant, on ne prête peut-être pas trop d’attention aux conventions de codage. Cependant, sur les projets collaboratifs, ils sont indispensables. Le style et les conventions de codage aident les lecteurs de code en indiquant ce que fait le code. Par exemple, il est assez courant d’avoir des noms de classe dont la première lettre est en majuscule, puis d’utiliser camelCase pour le reste du nom. Cette convention facilite le repérage des classes.
Faites défiler pour continuer
Les conventions donnent également au code la même apparence tout au long d’un projet afin qu’un lecteur n’ait pas à «réajuster» chaque fois qu’il regarde une partie différente. Ils permettent également une configuration cohérente de l’éditeur. Par exemple, il est assez courant d’avoir une longueur de ligne maximale dans les projets, interdisant à toute ligne de code de dépasser n caractères. Cela permet aux personnes travaillant sur le projet de configurer leurs éditeurs afin qu’ils puissent avoir deux fichiers ouverts en même temps côte à côte. Si cette limite n’est soudainement pas appliquée dans un fichier, cela devient très ennuyeux car il faut réajuster l’éditeur pour voir toute la ligne.
Peu importe quelle est la convention du moment qu’il y en a une et qu’elle est suivie de façon cohérente. Par exemple, il serait très ennuyeux qu’un programmeur utilise snake_case pour les variables tandis qu’un autre utilise camelCase sur le même projet. Un moyen simple de trouver de bonnes conventions est de voir s’il en existe une standard pour le langage, comme PEP8 de Python. Ils viennent généralement aussi avec des linters pour les éditeurs afin qu’ils se plaignent si la convention n’est pas suivie. Google a également des conventions pour les langues qu’ils utilisent.
6. Écrire des tests
Un aspect qui n’est pas enseigné aux débutants dès le début est que vous devez tester votre code. Dans les projets plus importants, cela est plus important car les tests agissent à la fois comme un élément de documentation pour le code et fournissent la certitude que le code se comporte comme il le fait. Mais même sur des projets d’une seule personne, ils sont utiles car ils permettent de faire plus facilement le refactoring et agissent comme un booster de confiance.
Un test de code est un simple script qui teste un aspect de votre code, généralement une fonction ou une classe. Un test pour une fonction expliquerait ce qu’elle teste et configurerait les variables d’entrée de la fonction et aurait défini une sortie attendue. Le test appelle ensuite la fonction testée avec ses variables d’entrée définies, capture la réponse et vérifie qu’elle est comme prévu. Par exemple, si nous testons une fonction qui additionne deux nombres, nous pourrions écrire un test appelé « TestAddIntegers » qui appelle la fonction avec les nombres 2 et 3 et vérifie que la réponse est 5.
Cependant, généralement, il ne suffit pas d’avoir un seul test par fonction. Ce qui est important à tester, ce sont tous les cas extrêmes et les cas plus rares. La fonction peut-elle additionner des nombres négatifs ? Peut-il ajouter des flotteurs ? Génère-t-il une erreur si nous lui donnons différents types, par exemple des chaînes ?
Il y a beaucoup de débats sur combien on devrait tester son code et quelles parties et de quelle manière. Cela mérite un article de blog à lui tout seul. Il semble y avoir un bon consensus sur le fait que les programmes informatiques devraient avoir une certaine forme de tests.
7. Utilisez les espaces blancs et commandez à votre avantage
Un aspect de la programmation qui est rarement mentionné est la manière dont les instructions sont ordonnées et organisées. J’aime considérer la programmation comme un processus d’écriture. Lors de l’écriture, nous avons des structures et des techniques qui nous aident à communiquer avec le lecteur. Nous avons des mots individuels, des phrases, des paragraphes, des signes de ponctuation et d’autres signes de ponctuation qui nous aident à transmettre notre idée au lecteur. Dans le code, nous avons différentes structures. Nous avons des fonctions, des objets, des instructions, des affectations, des expressions et, plus important encore, des espaces. Ces structures sont différentes de ce que nous utilisons lorsque nous écrivons de la prose, mais nous devrions les utiliser dans le même but, pour communiquer efficacement ce que fait notre code. De la même manière que nous n’introduirons pas plus d’une idée dans un paragraphe, nous ne devrions pas exécuter deux instructions non liées dans le même bloc de code.
Une bonne métrique à laquelle il faut penser lors du classement des instructions est qu’il faut minimiser la durée de vie des variables. La durée de vie d’une variable est le nombre de lignes entre la première et la dernière fois qu’elle a été utilisée. Lire du code avec de longues durées de vie variables est difficile car il faut garder les variables à l’esprit pendant longtemps, ce qui augmente la charge cognitive. Si une variable est utilisée à la place dans un bloc de 10 lignes, par exemple, il est beaucoup plus facile de garder une trace, et on n’a pas besoin d’y penser après ce bloc. Bien faire cela est parfois difficile, mais ajouter des fonctions d’assistance et des espaces blancs aux bons endroits aide.
Sommaire
J’espère que ces conseils pour écrire un code meilleur et plus lisible vous ont été utiles et que vous les garderez à l’esprit la prochaine fois que vous programmerez. Si vous avez des conseils pour améliorer la lisibilité du code, j’aimerais en entendre parler dans les commentaires.
Tout autre commentaire est également le bienvenu. Je pourrais écrire des articles sur chacun de ces aspects plus en détail ultérieurement, donc tout bon conseil ou suggestion sur ce que vous voulez en savoir plus sera très apprécié.
Cet article est exact et fidèle au meilleur de la connaissance de l’auteur. Le contenu est uniquement à des fins d’information ou de divertissement et ne remplace pas un conseil personnel ou un conseil professionnel en matière commerciale, financière, juridique ou technique.
Brian29 le 04 juin 2018 :
Merci pour cet article.
Maintenant, je travaille comme écrivain sur https://coolessay.net/, mais j’ai toujours été intéressé par la programmation puisque mon père travaille comme programmeur depuis plus de 20 ans.
Maintenant, j’essaie d’apprendre autant que possible des informations utiles sur la programmation et les bases des algorithmes. Maintenant j’apprends le C#, et bien qu’il soit similaire aux langages de programmation « C », sa syntaxe m’a semblé difficile à apprendre. Je serais très reconnaissant si quelqu’un me conseillait sur des cours en ligne ou des livres sur le langage de programmation C#.
Merci de partager des informations aussi importantes et utiles.
