Comment écrire des commentaires en Python pour un code propre et lisible

Écrire de bons commentaires en Python permettra aux autres développeurs et testeurs de lire et de comprendre facilement votre code.

Un code propre avec une syntaxe cohérente, une dénomination descriptive des variables et une indentation est comme le premier livre, plus facile à comprendre et à maintenir.

De plus, de nos jours, il est moins courant qu’un individu écrive le code complet de l’ensemble de l’application ou du logiciel ; il s’agit plutôt d’une équipe ou d’un groupe de personnes qui travailleront vers le même objectif. Dans ce cas, un code propre et lisible rend la collaboration plus simple et plus efficace.

Les développeurs et les testeurs visent toujours à déployer des logiciels sans bug en production. L’écriture de code propre et lisible accélère ce processus en rendant le débogage plus simple et plus précis. Bien que vous trouviez quelques erreurs dans la production, un code plus propre est plus facile à mettre à jour.

Plus important encore, un code propre et lisible dure plus longtemps car il reste à jour au fil du temps.

Enfin, il est crucial de disposer d’un code propre et lisible pour créer un logiciel durable. Mais la question est : comment y parvenir exactement ? Eh bien, une méthode consiste à utiliser les commentaires.

N’est-il pas frustrant d’avoir écrit tout le code d’une logique complexe, mais de ne plus pouvoir reprendre là où on s’était arrêté le lendemain ? Cela n’arrive pas lorsque vous écrivez des commentaires.

Les commentaires sont un langage humain expliquant ce que fait le code source. Vous pouvez les écrire dans n’importe quelle langue, de préférence en anglais, car c’est une langue mondiale.

Ainsi, chaque fois que vous revenez à votre code source après des jours, voire des années, les commentaires vous expliqueront ce que vous avez écrit une fois.

En outre, ils aident les autres développeurs à comprendre facilement votre code. C’est pourquoi le code écrit avec des commentaires reste éternel, même en l’absence de son auteur.

De plus, il est assez courant d’avoir des conflits lorsqu’on utilise différents langages de programmation, surtout lorsque l’on travaille en équipe. C’est là que les commentaires viennent à la rescousse. Même si vous ne connaissez pas le langage de programmation du code source écrit par votre coéquipier, les commentaires vous aident à comprendre la logique qui se cache derrière.

La documentation du code est un moyen plus complet de gérer votre code source et permet à votre équipe de collaborer de manière transparente. Il contient tout ce qui concerne le code, comme la conception, les fonctionnalités, l’architecture, les composants, etc.

Les commentaires contribuent même à cette documentation de code. Des commentaires bien rédigés peuvent être directement intégrés dans la documentation du code afin que les développeurs comprennent non seulement le quoi et le pourquoi, mais également le comment de votre code.

• Les commentaires ne se contentent pas de lire le code, mais vous aident également à comprendre l’intention du développeur derrière chaque ligne. Ainsi, si vous trouvez un bug à l’avenir, vous saurez exactement où effectuer les mises à jour du code.
• Vous pouvez rédiger des commentaires sous forme de paragraphe pour l’intégralité du code ou pour des lignes individuelles expliquant le rôle de chaque bloc de code. De cette façon, ils vous permettent, ainsi qu’aux autres développeurs, de bien comprendre le code, améliorant ainsi la lisibilité.
• Les commentaires peuvent diviser le code en sections logiques, simplifiant ainsi la navigation dans le code.
• Vous devez inclure des commentaires détaillant les entrées, les sorties et les cas d’utilisation attendus afin qu’un testeur puisse lire votre code.
• Enfin, mettre des commentaires bien rédigés dans votre documentation améliore la lisibilité globale de la documentation du code.

Les commentaires en Python commencent par un symbole dièse (#). Ainsi, lorsque vous démarrez une ligne avec un hachage (#), tout ce qui est écrit dans cette ligne est traité comme un commentaire.

Lorsque vous exécutez le code, le compilateur ignore la ligne commençant par hash (#) comme si elle n’existait même pas. Cependant, les commentaires restent visibles dans le code source pour remplir leur fonction.

Il existe trois types principaux.

Ce sont ceux que vous avez vus ci-dessus. Ils commencent par le symbole dièse (#). Fondamentalement, la ligne commençant par le symbole dièse (#) est dédiée au commentaire. C’est ce qu’on appelle un commentaire sur une seule ligne, où vous pouvez écrire un commentaire sur une seule ligne commençant par un hachage (#).

Voici comment rédiger des commentaires sur une seule ligne

# This is single line comment.

Techniquement, Python ne prend pas en charge les commentaires multilignes, mais il existe des moyens d’y parvenir en Python.

Vous pouvez également utiliser le hachage (#) pour écrire des commentaires sur plusieurs lignes. Chaque ligne que vous écrivez doit commencer par un symbole dièse (#) ici.

# This is the first comment.
# This is second comment.
# This is the last comment.

#3. Docstrings Python

Une façon courante d’écrire des commentaires sur plusieurs lignes consiste à utiliser des chaînes littérales – «  » »…. » » ». Lorsque vous écrivez quelque chose entre guillemets triples, le compilateur Python ignore ces lignes et exécute la partie restante du fichier.

Ces commentaires sont appelés docstrings lorsqu’ils sont écrits juste après les fonctions, modules et classes.

Voici la syntaxe pour faire cela

""" Multi-line comments using docstrings 
in Python. """

La rédaction de commentaires clairs et détaillés améliore la lisibilité et la maintenance de votre code. Voici donc les meilleures pratiques pour des commentaires clairs en Python.

Les commentaires ne doivent pas simplement raconter ce que fait le code, mais plutôt refléter le but et l’intention derrière chaque ligne.

Supprimez les commentaires obsolètes et assurez-vous de mettre à jour les commentaires chaque fois que vous modifiez le code.

Au lieu de longues histoires, écrivez des commentaires courts et précis.

Bad example: The function takes a,b as input, calculates a + b, and returns the value.
Good example: The function returns the sum of a and b.

L’utilisation de noms significatifs et descriptifs pour les variables et les noms de fonctions peut éliminer les commentaires redondants.

Coder d’abord ? Ou commenter d’abord ? Commenter avant de coder est la meilleure pratique ; c’est-à-dire, écrivez vos commentaires puis le code correspondant. De cette façon, vous pouvez d’abord penser à la logique, puis la convertir en code.

# Returns true if the cnt is less than 1.
return cnt < 1

Utilisez un format de commentaire cohérent comme l’espacement, l’indentation, le type de commentaires, etc., pour l’ensemble du code. Ce sera moins déroutant et plus organisé pour les lecteurs.

Utilisez des docstrings pour expliquer les fonctions et les classes en Python, comme indiqué dans l’exemple suivant.

def add_num(a,b):
    """ this function returns the sum of a and b """
    sum = a+b
    return sum

Évitez les commentaires inutiles dans votre code. Par exemple, la ligne de code suivante n’a pas besoin de commentaire pour être comprise.

ans = 42

#1. Éditeur de code Visual Studio

Éditeur de code Visual Studio est le meilleur IDE construit par Microsoft pour un environnement de développement complet. Avec la prise en charge native de Node.js et de JavaScript, l’outil prend également en charge de manière transparente de nombreux autres langages de programmation.

Cet outil hautement personnalisable dispose de diverses extensions pour différentes fonctionnalités. « Better Comments » est l’une de ces extensions qui vous permet de créer des commentaires conviviaux.

Vous pouvez classer vos commentaires en alertes, requêtes, faits saillants, etc., pour une navigation plus facile.

Le code VS prend en charge l’édition multi-curseur afin que vous puissiez commenter ou modifier plusieurs lignes simultanément.

Cet éditeur est disponible sur toutes les principales plates-formes comme Mac, Windows et Linux.

#2. Texte sublime

Texte sublime est l’éditeur incontournable pour les grands projets et le codage lourd. L’éditeur est connu pour sa rapidité, sa personnalisation et ses raccourcis.

La puissante fonctionnalité de coloration syntaxique de l’outil vous aide à distinguer facilement le code des commentaires.

Comme le code VS, Sublime Text prend également en charge l’édition multi-curseur pour commenter plusieurs lignes en même temps.

Grâce à sa fonction de saisie semi-automatique. Vous n’avez pas besoin de répéter manuellement les lignes de code ; cette fonctionnalité complète automatiquement votre code en fonction des modèles, vous aidant ainsi à coder plus rapidement.

De plus, la fonctionnalité « Goto Anything » de l’outil vous permet de basculer de manière transparente entre les fonctions et les fichiers de votre projet.

#3. Bloc-notes++

Noepad++ est un éditeur de texte simple et populaire écrit en C++ et prend en charge de nombreux langages de programmation. Cela ne ressemble pas à un éditeur moderne comme VS Code ou Sublime Text ; son interface est très simple et semble faire ce dont elle a besoin.

Nodepad++ propose de nombreux raccourcis standards pour des commentaires efficaces. Vous pouvez également personnaliser le clavier de raccourci pour personnaliser votre expérience de commentaire.

Sa fonction d’arborescence des documents vous montre un aperçu de la structure du projet, vous permettant de naviguer de manière transparente dans les fichiers, les dossiers et le code.

#4. Vigueur

Vigueur L’IDE permet un développement et une exécution de code plus rapides. Tout et n’importe quoi peut être fait sur cet éditeur à l’aide de raccourcis clavier, vous devez donc déployer de sérieux efforts pour le maîtriser.

Cet éditeur centré sur le clavier offre également de nombreuses fonctionnalités de commentaires via des raccourcis clavier. Il dispose de fonctionnalités et de commandes puissantes pour naviguer efficacement dans les commentaires.

Ce logiciel léger peut gérer des fichiers volumineux et des centaines de langages de programmation. Qui déteste les trucs gratuits ? Comme tous les éditeurs de la liste, Vim est également entièrement gratuit et open source.

Il est disponible en natif sur les systèmes macOS et Linux et est téléchargeable sur Windows.

#5. PyCharm

PyCharm est un IDE puissant spécialement conçu pour le développement Python. Bien qu’il prenne en charge de nombreux autres langages de programmation, il fonctionne mieux avec Python. Il propose des fonctionnalités de complétion de code, de mise en évidence de la syntaxe et de débogage adaptées à Python.

De plus, cela rend les commentaires en Python beaucoup plus efficaces. Il fournit des fonctionnalités de navigation pour vous aider à accéder facilement à des commentaires spécifiques.

Obtenez divers modèles de commentaires et créez efficacement des modèles de commentaires personnalisés dans Pycharm.

De plus, les outils de refactorisation de l’éditeur vous permettent de mettre à jour ou de corriger facilement les commentaires.

Conclusion

Le respect des normes de code est nécessaire tout au long du processus de développement du code et obligatoire pour écrire du code prêt pour la production, car votre code doit être lisible par tous les autres développeurs et testeurs.

Une pratique importante pour créer un code lisible consiste à écrire des commentaires. Les commentaires sont disponibles dans presque tous les langages de programmation. Cependant, avec cet article, vous devriez maintenant savoir comment rédiger des commentaires Python, leurs types et les meilleures pratiques à suivre lors de la rédaction de commentaires.

En outre, les meilleurs éditeurs de code qui vous aident dans la gestion des commentaires sont répertoriés.