Ce tutoriel tiré de mon prochain livre de programmation "From One to Zero" (NoStarch, 2021) vous montrera comment écrire d'excellents commentaires. Alors que la plupart des didacticiels en ligne se concentrent sur une liste à puces de conseils de commentaire, nous plongeons plus profondément dans la viande en explorant les raisons sous-jacentes des principes de commentaire couramment recommandés. Alors, commençons !
Code pour les humains et non les machines
"N'importe quel imbécile peut écrire du code qu'un ordinateur peut comprendre. Les bons programmeurs écrivent du code que les humains peuvent comprendre." — Martin Fowler
Le but principal du code source est de définir ce que les machines doivent faire et comment le faire.
Pourtant, si c'était le seul critère, vous utiliseriez un langage machine de bas niveau tel que l'assembleur pour atteindre cet objectif car c'est le langage le plus expressif et le plus puissant.
Le but des langages de programmation de haut niveau tels que Python est d'aider les gens à écrire un meilleur code et à le faire plus rapidement. Notre prochain principe pour un code propre est de vous rappeler constamment que vous écrivez du code pour d'autres personnes et non pour des machines.
Si votre code a un impact dans le monde réel, il sera lu plusieurs fois par vous ou un programmeur qui prend votre place si vous arrêtez de travailler sur la base de code. Supposez toujours que votre code source sera lu par d'autres personnes. Que pouvez-vous faire pour faciliter leur travail ? Ou, pour le dire plus clairement :que pouvez-vous faire pour atténuer les émotions négatives qu'ils ressentiront contre le programmeur original de la base de code sur laquelle ils travaillent ? Code pour les personnes et non les machines !
Réduire le temps de compréhension
Si vous écrivez du code pour les humains et non pour les machines, vous devrez utiliser des commentaires pour aider les lecteurs de votre code à le comprendre mieux et plus rapidement. Un court commentaire peut réduire considérablement le temps nécessaire pour saisir cognitivement la signification de la base de code. Prenons l'exemple de code suivant :
import re
text = '''
Ha! let me see her: out, alas! he's cold:
Her blood is settled, and her joints are stiff;
Life and these lips have long been separated:
Death lies on her like an untimely frost
Upon the sweetest flower of all the field.
'''
f_words = re.findall('\\bf\w+\\b', text)
print(f_words)
l_words = re.findall('\\bl\w+\\b', text)
print(l_words)
'''
OUTPUT:
['frost', 'flower', 'field']
['let', 'lips', 'long', 'lies', 'like']
'''
Mauvais exemple de code sans commentaires.
L'extrait de code précédent analyse un court extrait de texte de Roméo et Juliette de Shakespeare. à l'aide d'expressions régulières. Si vous n'êtes pas très familier avec les expressions régulières, vous avez probablement du mal à comprendre ce que fait le code. Même les noms de variables significatifs n'aident pas beaucoup. Voyons si quelques commentaires peuvent résoudre votre confusion !
import re
text = '''
Ha! let me see her: out, alas! he's cold:
Her blood is settled, and her joints are stiff;
Life and these lips have long been separated:
Death lies on her like an untimely frost
Upon the sweetest flower of all the field.
'''
# Find all words starting with character 'f'
f_words = re.findall('\\bf\w+\\b', text)
print(f_words)
# Find all words starting with character 'l'
l_words = re.findall('\\bl\w+\\b', text)
print(l_words)
'''
OUTPUT:
['frost', 'flower', 'field']
['let', 'lips', 'long', 'lies', 'like']
'''
Bon exemple de code avec commentaires.
Les deux courts commentaires aident grandement à comprendre les modèles d'expression régulière '\\bf\w+\\b' et '\\bl\w+\\b' . Bien que je ne plongerai pas profondément dans les expressions régulières ici, l'exemple montre comment les commentaires peuvent vous aider à comprendre grossièrement le code des autres sans comprendre chaque sucre syntaxique. Pour des didacticiels d'introduction aux puissantes expressions régulières de la technologie, consultez nos deux livres techniques Python One-Liners et La manière la plus intelligente d'apprendre les expressions régulières Python .
Vous êtes l'expert :partagez votre sagesse !
Des commentaires utiles donnent un aperçu de votre réflexion - comme vous avez écrit le code, vous possédez un aperçu précieux de celui-ci, qui n'est égalé que par très peu de personnes. Ne manquez pas de partager vos idées avec d'autres personnes ! Les commentaires peuvent être très utiles pour « résumer » des blocs de code. Par exemple, si vous avez cinq lignes de code traitant de la mise à jour des informations client dans une base de données, ajoutez un court commentaire avant le bloc pour l'expliquer. Cela aidera le lecteur à obtenir un aperçu rapide de votre code et accélérera son "temps de chargement du code", ainsi que le vôtre. Vous pouvez trouver un exemple d'une telle instance ci-dessous :
# Process next order order = get_next_order() user = order.get_user() database.update_user(user) database.update_product(order.get_order()) # Ship order & confirm customer logistics.ship(order, user.get_address()) user.send_confirmation()
Les blocs commentés aident à avoir un aperçu du code.
Le code illustre la manière dont une boutique en ligne traite une commande client en deux étapes de haut niveau :(1) Traitement de la commande suivante et (2) Expédition de la commande. Les commentaires vous aident à comprendre le but du code en quelques secondes sans avoir besoin de regarder chaque appel de méthode individuel.
Commentaires sous forme d'AVERTISSEMENTS !
Vous pouvez également utiliser des commentaires comme avertissement de conséquences potentiellement indésirables. Cela augmente le niveau d'attention du programmeur travaillant avec votre code. Le code suivant montre un tel exemple où les programmeurs sont avertis avant d'appeler une fonction ship_yacht() qui expédiera un yacht coûteux à un client.
##########################################################
# WARNING #
# EXECUTING THIS FUNCTION WILL SHIP A $1,569,420 YACHT!! #
##########################################################
def ship_yacht(customer):
database.update(customer.get_address())
logistics.ship_yacht(customer.get_address())
logistics.send_confirmation(customer)
Commentaires sous forme d'avertissements.
Il existe de nombreuses autres façons d'utiliser les commentaires de manière utile. Les commentaires sont toujours là pour le lecteur humain, alors gardez toujours à l'esprit que vous écrivez du code pour les humains et non pour les machines !
Évitez les commentaires inutiles
Tous les commentaires n'aident pas les lecteurs à mieux comprendre le code. En fait, il existe de nombreux cas où les commentaires réduisent la clarté et confondent les lecteurs d'une base de code donnée. Si votre objectif est d'écrire du code propre, vous devez non seulement utiliser des commentaires utiles, mais également éviter les commentaires inutiles. Mais que sont les commentaires inutiles ? Plongeons-nous ensuite dans ceux-ci.
Pendant mon temps en tant que chercheur en informatique, beaucoup de mes étudiants de niveau supérieur m'ont décrit en détail comment se déroulaient leurs entretiens d'embauche dans diverses entreprises. Un étudiant très qualifié avait postulé avec succès pour un emploi chez Google. Il m'a dit que les chasseurs de têtes de Google - ce sont généralement des ingénieurs de Google - ont critiqué son style de code parce qu'il avait ajouté trop de commentaires inutiles. Ces types de commentaires sont appelés "odeurs de code" - les codeurs experts peuvent déterminer très rapidement si vous êtes vous-même un codeur débutant, intermédiaire ou expert. Les commentaires inutiles rendent cela très évident. Mais que sont les commentaires inutiles ? Dans la plupart des cas, ils ajoutent un niveau de redondance au code. Un bon codeur utilisera des noms de variables significatifs (Principe :Utilisez les bons noms ), de sorte que le code devient souvent explicite, du moins par rapport au code qui n'utilise pas les bons noms. Revoyons l'extrait de code avec des noms de variables significatifs.
investments = 10000
yearly_return = 0.1
years = 10
for year in range(years):
print(investments * (1 + yearly_return)**year)
Aucun commentaire nécessaire.
Le code calcule votre retour sur investissement cumulé pendant dix ans en supposant un rendement de 10 %. Maintenant, ajoutons quelques commentaires inutiles !
investments = 10000 # your investments, change if needed
yearly_return = 0.1 # annual return (e.g., 0.1 --> 10%)
years = 10 # number of years to compound
# Go over each year
for year in range(years):
# Print value of your investment in current year
print(investments * (1 + yearly_return)**year)
Commentaires inutiles.
Tous les commentaires dans l'extrait de code précédent sont redondants. Certains d'entre eux auraient été utiles si vous aviez choisi des noms de variables moins significatifs tels que x , y , ou z . Mais expliquer une variable nommée yearly_return au moyen d'un commentaire ne fournit aucune valeur relative. Bien au contraire, cela réduit la valeur car cela ajoute un encombrement inutile au code. L'encombrement supplémentaire rend votre code moins lisible et moins concis. Il existe quelques règles qui peuvent vous aider à éviter les commentaires inutiles, bien que la meilleure règle soit d'utiliser votre bon sens pour déterminer si un commentaire améliore réellement la lisibilité de votre code.
Code Smells – Principes des commentaires négatifs
- N'utilisez pas de commentaires en ligne. Ils ont peu de valeur et peuvent être complètement évités en choisissant des noms de variables significatifs.
- Ne soyez pas redondant. La redondance est l'ennemie de la clarté, cela vaut aussi pour les commentaires !
- N'ajoutez pas de commentaires évidents. Vous pouvez voir un commentaire évident dans l'extrait de code précédent juste avant le
fordéclaration de boucle. Tout codeur connaît leforboucle, alors quelle valeur supplémentaire fournissez-vous avec le commentaire# Go over each yearlorsque la boucle for indique déjàfor year in range(years)? - Ne commentez pas le code. Si vous êtes un programmeur, il est très probable que vous en soyez coupable. Nous, les programmeurs, nous accrochons souvent à nos extraits de code bien-aimés même si nous avons déjà (à contrecœur) décidé de les supprimer. L'approche timide pour supprimer le code inutile consiste à le commenter. Cependant, le code commenté est un tueur de lisibilité et vous devez l'éviter à tout prix si vous voulez écrire du code propre. Au lieu de commenter le code inutile, supprimez-le hardiment. Pour votre tranquillité d'esprit, vous devez utiliser un outil d'historique des versions tel que Git qui vous permet d'obtenir n'importe quel ancien extrait de code si vous en avez besoin.
De nombreux langages de programmation tels que Python sont livrés avec une fonctionnalité de documentation qui vous permet de décrire le but de chaque fonction, méthode et classe dans votre code. Si vous avez soigneusement choisi le niveau d'abstraction de chaque fonction (principe de responsabilité unique ), il suffit souvent d'utiliser la fonctionnalité de documentation intégrée au lieu de commentaires pour décrire ce que fait votre code. Cela supprime en grande partie le besoin de commentaires supplémentaires dans votre code.
Voulez-vous développer les compétences d'un professionnel Python complet —tout en étant payé dans le processus ? Devenez freelance Python et commandez votre livre Leaving the Rat Race with Python sur Amazon (Kindle/Print ) !
