Commenter votre code est une bonne pratique si vous voulez aider d’autres personnes à comprendre ce que vous avez écrit. Cela rend crucial d’apprendre à commenter en Python si vous travaillez dans une grande équipe.
Cependant, il est également très important de comprendre ce que vous avez écrit à un moment dans le futur. Revenir à l’ancien code peut être désorientant, et c’est un problème si vous espérez offrir un support continu pour une application.
Lisez aussi: Comment utiliser des chaînes en Python
Dans cet article, nous allons voir comment commenter en Python et comment commenter de manière logique et utile.
Comment commenter en Python et le rendre utile
La bonne nouvelle est qu’il est extrêmement facile de commenter en Python. Vous devez simplement préfixer tout ce que vous allez taper avec un hashtag:
#This is a comment!
De cette façon, tout ce que vous avez écrit sera ignoré par l’interpréteur et mis en surbrillance pour toute personne consultant votre code. Vous pouvez placer un commentaire Python sur sa propre ligne, ou même en ligne avec le code que vous souhaitez expliquer.
Il est donc facile d’apprendre à commenter en Python; le plus difficile est de savoir quand commenter et comment s’assurer que ces commentaires sont lisibles et utiles.
Lisez aussi: Comment imprimer en Python
Pour cela, vous pouvez vous assurer que vos commentaires respectent les meilleures pratiques de base. Selon le Guide de style pour le code Python, vous devriez viser à garder vos commentaires en dessous de 79 caractères par ligne. Cela empêche le lecteur d’avoir à faire défiler horizontalement et garde tout propre.
Bien que les commentaires en ligne puissent être utiles, notez que leur placement consécutif peut compliquer la connaissance du code et de ce qui ne l’est pas, ce qui rend l’interprétation du programme beaucoup plus difficile en un coup d’œil.
C’est déroutant, par exemple:
if baddyX + 40 > mineX and baddyY + 40 > mineY and baddyX < mineX + 0 and baddyY < mineY + 19: #Checks the position of the bad guy in relation to the mine
baddyX = 10000 #Sets the position of the bad guy to be far off the screen out of site
pygame.display.update() #Updates the graphics reflecting the new positions
for event in pygame.event.get(): #Looks for an event
if event.type == pygame.QUIT: #If the event is the player clicking the cross
run = False
Une bien meilleure façon de réaliser quelque chose de similaire serait:
#If the baddy overlaps the mine, then the baddy is sent off page and the graphics update. Then we will check for events.
if baddyX + 40 > mineX and baddyY + 40 > mineY and baddyX < mineX + 0 and baddyY < mineY + 19:
baddyX = 10000
pygame.display.update()
for event in pygame.event.get():
if event.type == pygame.QUIT:
run = False
Mais bien sûr, l'un ou l'autre serait un exemple de commentaire inutile!
Quand et comment commenter en Python
Quant à ce qui doit être commenté…
Voici quelques légendes courantes et utiles à ajouter à votre code:
- Un peu sur toute nouvelle fonction et ce qu'elle fait
- Une explication de ce qu'est une variable ou un ensemble de variables
- Expliquer pourquoi vous avez fait quelque chose d'une certaine manière (si ce n'est pas évident)
- Mettre en évidence la clé et les parties importantes de votre code
- Fournir des avertissements
Quelques conseils utiles pour garder les commentaires utiles plutôt que distrayants:
- Gardez les commentaires succincts et pas plus que nécessaire - soyez respectueux du temps de votre lecteur!
- Évitez les commentaires qui indiquent l'évidence; ne fais pas plus de commentaire
- Ne vous contentez pas d'expliquer quelle quelque chose fait: expliquer Pourquoi vous le mettez là et pourquoi c'est important
- Soyez poli et amical! N'utilisez absolument pas de commentaires pour faire honte aux autres codeurs. C'est un moyen rapide de devenir la personne la moins populaire de votre équipe.
Plus d'utilisations pour les commentaires Python
L'utilisation principale pour apprendre à commenter en Python est de fournir des conseils et des instructions utiles. Cela peut aider les autres à naviguer dans le code. Cela dit, il existe d'autres scénarios où l'utilisation de code peut être utile.
Lisez aussi: Comment créer un fichier en Python et plus
Les commentaires d'en-tête, par exemple, vont en haut d'un fichier et peuvent aider à expliquer ce que fait le code en dessous. Cela pourrait même inclure des instructions utiles qui aideront le lecteur à trouver des fonctions importantes.
Les commentaires d'en-tête peuvent également être utilisés pour insérer un avis de droit d'auteur ou pour déclarer votre paternité du code. Certaines personnes aiment utiliser des codes ASCII exagérés pour donner à leur code des titres flamboyants.
Une autre utilisation des commentaires Python est de vous aider à trouver rapidement votre chemin dans votre code avec l'outil de recherche. Je vais souvent me laisser des commentaires afin de pouvoir sauter rapidement entre différents points de mon code, ou pour marquer quelque chose que je dois faire plus tard. Si je laisse quelque chose d'inachevé, je vais souvent y faire des commentaires afin que je puisse le retrouver facilement à une date ultérieure.
Enfin, vous pouvez utiliser des commentaires en Python pour faire des blagues. Cela irritera certaines personnes et ne rendra certainement pas votre code aussi propre et efficace que possible. Mais personnellement? Je trouve que la programmation peut être un travail solitaire, et parfois trouver un peu d'esprit ou de «bonjour» peut remonter le moral.
Ça ne coûte rien d'être gentil!
Pensées de clôture
Gardez à l'esprit que savoir comment commenter en Python ne vous dispense pas d'avoir à écrire du code propre et lisible. Vos commentaires devraient servir de conseils supplémentaires utiles aux lecteurs, pas une pierre de Rosette pour décoder vos divagations folles!
Cela signifie que vous devez également:
- Structurez votre code de manière logique
- Utilisez des noms intelligents pour les variables et les fonctions, ainsi qu'une convention de dénomination cohérente
- Utiliser correctement les nouvelles lignes et indentations (heureusement, Python nous oblige à faire ces dernières)
Il y a ceux qui pensent que commenter le code est en fait une indication que le code n'était pas bien écrit au départ. Cette foule prêche en fait contre l'utilisation des commentaires!
En fin de compte, la façon dont vous choisissez avec parcimonie ou générosité de commenter votre code est une question de préférence personnelle. Mais gardez à l'esprit que quelqu'un qui regarde votre code peut ne pas être aussi expérimenté que vous, et un petit conseil pourrait être d'une grande aide! L'objectif principal est de garantir que toute personne qui a besoin de comprendre votre code puisse le faire, et tant que c'est le cas, c'est à vous de décider comment vous y prendre!
Voilà comment commenter en Python. Qu'est-ce que vous trouvez utile / irritant lors de la lecture du code? Y a-t-il quelque chose que nous avons manqué? Faites-le nous savoir dans les commentaires ci-dessous!
Si vous souhaitez en savoir plus sur le codage Python, nous vous recommandons d'essayer un cours en ligne. C'est le meilleur moyen de se familiariser rapidement avec un nouveau langage de programmation. Découvrez notre ventilation des meilleures options.
