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

Traducteur | Zhao Qingyu

Critique | Sun Shujuan

Regardez-vous souvent le code que vous avez écrit il y a 6 mois et souhaitez-vous savoir ce qui se passe dans ce code ? Ou vous reprenez un projet de quelqu'un d'autre et vous ne le faites pas ? Je ne sais pas. Par où commencer ? Cette situation est relativement courante pour les développeurs. Il existe de nombreuses méthodes en Python qui nous aident à comprendre le fonctionnement interne du code. Ainsi, lorsque vous examinez le code depuis le début ou écrivez du code, il devrait être plus facile de continuer là où vous vous êtes arrêté.

Ici, je vais vous donner un exemple. Nous pouvons obtenir le code comme indiqué ci-dessous. Ce n'est pas le pire, mais il y a certaines choses que nous devons confirmer, telles que :

• Que signifient f et d dans la fonction load_las_file
• Pourquoi vérifions-nous les résultats dans la fonction clay ? ces fonctions nécessitent quel type de flotteurs ou de DataFrames ?

Dans cet article, je couvrirai 5 conseils de base sur la façon d'améliorer la lisibilité de votre application/script grâce à la documentation, à la saisie rapide et aux noms de variables appropriés.

1. Commentaires

La première chose que nous pouvons faire avec le code est d'ajouter des commentaires à certaines lignes, mais attention à ne pas trop commenter. Les commentaires doivent expliquer pourquoi le code fonctionne, ou pourquoi quelque chose est fait d'une certaine manière, plutôt que comment il est implémenté. Les commentaires en Python sont généralement complétés à l'aide du signe dièse (#), qui peut 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 des guillemets doubles.

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

Dans l'exemple ci-dessous, quelques commentaires ont été ajoutés au code pour expliquer comment certaines lignes de code fonctionnent et pourquoi :

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, en revanche, implique de déclarer explicitement le type de variable et ne peut pas changer pendant l'exécution du code.

En 2014, la PEP 484 a introduit le concept d'indices de type, et ce concept a ensuite été introduit dans Python 3.5. Cela vous permet de déclarer explicitement des types de variables. En ajoutant des indices de type, vous pouvez améliorer considérablement la lisibilité de votre code. Dans l'exemple suivant, nous pouvons voir :

nécessite deux paramètres

• Le type de paramètre filename est une chaîne
• Le type de paramètre start_third est de type float, et la valeur par défaut de ce paramètre est None
• La fonction retournera Un objet Pandas DataFrame

Sur la base des indices de type, nous savons exactement ce dont la fonction a besoin et ce qu'elle retournera.

3. Chaîne de documentation

La chaîne de documentation est la chaîne qui suit immédiatement la définition de la fonction ou de la classe. Les docstrings sont un excellent moyen d'expliquer en détail ce que fait une fonction, quels arguments elle prend, quelles exceptions elle lancera, sa valeur de retour, et plus encore. De plus, si vous utilisez un outil tel que Sphinx pour créer une documentation en ligne pour votre code, les docstrings seront automatiquement extraits et convertis en documentation appropriée. L'exemple suivant montre la docstring d'une fonction nommée clay_volume. Ici, nous pouvons préciser la signification de chaque paramètre. Cela le rend plus détaillé que les indications de type de base. Vous pouvez également inclure plus d'informations sur la méthodologie derrière la fonction, telles que des références académiques ou des équations.

Les chaînes Doc sont également très utiles lorsque nous appelons des fonctions ailleurs dans le code. Par exemple, lorsque vous écrivez du code à l'aide de Visual Studio, vous pouvez survoler un appel de fonction et afficher une fenêtre contextuelle indiquant ce que fait la fonction et ce dont elle a besoin.

Si vous utilisez Visual Studio Code (VS Code) pour modifier votre code Python, vous pouvez utiliser des extensions comme autoDocstring pour faciliter le processus de création de docstrings. Vous pouvez saisir trois guillemets doubles et le reste du modèle sera automatiquement rempli. Il vous suffit de remplir les détails.

Astuce : Si vous avez déclaré des types dans les paramètres, ils seront automatiquement sélectionnés.

4. Noms de variables lisibles

Parfois, lorsque vous écrivez du code, vous ne vous souciez pas trop des noms de variables, surtout lorsque le temps presse. Cependant, si vous regardez le code et que vous trouvez une série de variables nommées x1 ou var123, vous ne comprendrez peut-être pas au premier coup d'œil ce qu'elles représentent. Dans l'exemple ci-dessous, il y a deux variables f et d. Nous pouvons deviner la signification de ces variables en examinant d’autres parties du code, mais cela peut prendre du temps, surtout si le code est long.

Si nous donnons des noms appropriés à ces variables, nous pourrons savoir que l'une des variables est le fichier data_file lu par l'appel lasio.read(), et est très probablement les données d'origine. La variable data nous indique que ce sont les données réelles que nous traitons.

5. Évitez les nombres magiques

Les nombres magiques sont des valeurs dans le code qui ont une signification inexpliquée derrière elles et peuvent être des constantes. Leur utilisation dans le code peut provoquer une ambiguïté, surtout si vous n'êtes pas familier avec l'utilisation de nombres dans les calculs. De plus, si nous avons le même nombre magique à plusieurs endroits, lorsqu'il doit être mis à jour, nous devons en mettre à jour chaque instance. Cependant, si ces nombres se voient attribuer une variable nommée de manière appropriée, le processus de substitution devient beaucoup plus facile. Dans l'exemple ci-dessous, nous avons une fonction qui calcule une valeur appelée résultat et la multiplie par 0,6. Qu'est-ce que cela signifie ? Est-ce un facteur de conversion ? Un scalaire ?

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

6. Code final

Après avoir appliqué les conseils ci-dessus, notre code final semble désormais plus propre et plus facile à comprendre.

7. Résumé

L'ajout d'explications à votre code via des commentaires et des docstrings peut vous aider, vous et les autres, à comprendre ce que fait le code. Cela peut sembler une corvée au début, mais avec l’utilisation des outils et une pratique régulière, cela deviendra une seconde nature.

Lien original : https://towardsdatascience.com/5-essential-tips-to-improve-the-readability-of-your-python-code-a1d5e62a4bf0

Introduction du traducteur

Zhao Qingyu, rédacteur en chef de la communauté 51CTO, engagé en années de développement moteur. Ses intérêts de recherche incluent les domaines de la sécurité des systèmes d'exploitation et des réseaux sécurisés, et il a publié des brevets liés aux réseaux.

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!