Cinq conseils essentiels pour améliorer la lisibilité du code Python

Il existe de nombreuses méthodes en Python qui peuvent nous aider à comprendre le fonctionnement interne du code. De bonnes habitudes de programmation peuvent rendre notre travail plus efficace avec la moitié de l'effort !

Par exemple, nous pourrions nous retrouver avec un code qui ressemble beaucoup à l'image ci-dessous. Bien que ce ne soit pas le pire, nous devons cependant développer certaines choses, telles que :

• Que signifient f et d dans la fonction load_las_file ?
• Pourquoi vérifie-t-on le résultat en fonction argile ?
• Quels types sont requis pour ces fonctions ? Des flotteurs ? Des DataFrames ?

1. Commentaires

La première chose que nous pouvons faire à notre code est d'ajouter quelques commentaires à notre code, mais n'en abusez pas. Les commentaires doivent vous expliquer pourquoi le code fonctionne ou pourquoi quelque chose est fait d'une certaine manière, et non comment cela fonctionne.

Les commentaires en Python sont généralement rédigés à l'aide du signe dièse (#) et peuvent s'étendre sur une ou plusieurs lignes.

# Comment using the hashtag
# Another comment using the hashtag

Pour les commentaires sur plusieurs lignes, nous pouvons également utiliser trois guillemets doubles.

"""
This is an example of
a multi-line comment
"""

Dans l'exemple ci-dessous, des commentaires ont été ajoutés au code pour expliquer le workflow et le raisonnement derrière certaines lignes de code

2. Typage explicite

Le langage Python est typé dynamiquement, ce qui signifie que les types de variables sont vérifié uniquement au moment de l'exécution. De plus, les variables peuvent changer de type lors de l'exécution du code.

Le typage statique, quant à lui, implique d'indiquer explicitement le type d'une variable et celui-ci ne peut pas changer pendant l'exécution du code.

En 2014, la PEP 484 a introduit le concept d'indices de type, introduits plus tard dans Python 3.5, ceux-ci nous permettent d'indiquer explicitement le type d'une variable.

En ajoutant des indices de type, vous pouvez améliorer considérablement la lisibilité de votre code. Dans l'exemple suivant, nous pouvons facilement obtenir les informations suivantes :

La fonction nécessite deux paramètres

Le paramètre de nom de fichier doit être de type chaîne

Le paramètre start_degree doit être de type float, la valeur par défaut est Aucune

• Le la fonction retournera Un objet pandas DataFrame
• Nous pouvons immédiatement dire, en fonction des indices de type, exactement ce dont la fonction a besoin et ce qu'elle retournera.

3. Docstrings (chaînes de documentation)

Les chaînes de document sont des chaînes littérales qui suivent la définition d'une fonction ou d'une classe. Les Docstrings sont un excellent moyen d'expliquer en détail ce que fait notre fonction, quels paramètres elle prend et ce qu'elle fait. ce qui sera jeté, ce qu'il reviendra, etc.

De plus, si nous utilisons un outil comme Sphinx pour créer une documentation en ligne pour notre code, les docstrings seront automatiquement récupérés et convertis en documentation appropriée.

L'exemple ci-dessous montre la docstring d'une fonction nommée clay_volume .

Ici, nous pouvons spécifier ce qu'est chaque paramètre, ce qui est plus détaillé que les indices de type de base, et nous pouvons également inclure plus d'informations sur la méthode derrière la fonction, comme des références académiques ou des équations.

Avoir des docstrings est également très utile lorsque nous appelons des fonctions ailleurs dans le code. Par exemple, lorsque vous modifiez du code à l'aide de Visual Studio, vous pouvez survoler un appel de fonction et voir une fenêtre contextuelle indiquant ce que fait la fonction et ce dont elle a besoin.

Si vous utilisez Visual Studio Code (VSCode) pour modifier notre code Python, vous pouvez utiliser des extensions comme autoDocstring pour simplifier le processus de création de docstrings. Le plugin nous permet de saisir trois guillemets doubles et remplit automatiquement le reste du modèle, il suffit de se concentrer sur les autres détails qui doivent être renseignés.

4. Noms de variables lisibles

Souvent, lorsque nous écrivons du code, nous ne prêtons pas beaucoup d'attention aux noms de variables, surtout lorsque nous sommes impatients de remplir certaines fonctions. Mais si notre code renvoie une série de variables nommées x1 ou var123, personne ne pourra comprendre ce qu'elles représentent au premier coup d'œil.

Dans l'exemple ci-dessous, nous avons deux variables f et d. Il est possible de deviner ce que cela signifie en examinant d'autres parties du code, mais cela prend un certain temps, surtout si le code est long.

Si nous attribuons des noms appropriés à ces variables, nous pourrons savoir que l'une d'entre elles est le fichier data_file lu par l'appel lasio.read(), et est très probablement les données d'origine, et la variable data indique nous que c'est celui que nous utilisons les données réelles.

5. Éviter les nombres magiques

Les nombres magiques sont des valeurs dans le code qui ont de nombreuses significations inexpliquées derrière elles et peuvent représenter des constantes. Leur utilisation dans le code peut provoquer une ambiguïté, en particulier pour ceux qui ne sont pas familiers avec les calculs dans lesquels des nombres sont utilisés.

De plus, si nous avions le même nombre magique à plusieurs endroits et devions le mettre à jour, nous devrions en mettre à jour chaque instance. Cependant, l'ensemble du processus est beaucoup plus simple si vous attribuez les numéros à des variables correctement nommées.

Dans l'exemple ci-dessous, nous avons une fonction qui calcule une valeur appelée résultat et la multiplie par 0,6. Nous ne pouvons pas savoir exactement ce que signifie le code à partir du code

Si nous déclarons une variable et lui attribuons la valeur, alors nous avons plus de chances de savoir de quoi il s'agit. Dans ce cas, c'est le rapport argile/schiste utilisé pour convertir l'indice de rayons gamma en volume d'argile.

Résumé

L'ajout de documentation à notre code via des commentaires et des docstrings peut grandement nous aider, ainsi que les autres, à comprendre ce que fait le code. En effet, cela peut sembler une corvée au début, mais avec l’utilisation d’outils et une pratique régulière, cela peut devenir une seconde nature pour vous.

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!