Commentaires dans le code

5.1 Comment écrire des commentaires

En Python, comme dans de nombreux langages de programmation, tu peux écrire des commentaires dans le code. Les commentaires aident les développeurs et les autres membres du projet à comprendre le code, ce qui est particulièrement utile pour travailler en équipe et lors de la maintenance à long terme. En Python, il existe plusieurs façons d'ajouter des commentaires dans le code.

Commentaires sur une ligne:

Ils commencent par le symbole #. Tout ce qui suit # sur la même ligne est ignoré par Python. Ce type de commentaire est généralement utilisé pour des remarques courtes ou des explications pour une ligne de code particulière. Exemple :

# C'est un commentaire sur une ligne
print("Hello, World!") # Explication de l'action de la fonction

Commentaires multi-lignes :

En Python, il n'existe pas de syntaxe spéciale pour les commentaires multi-lignes, mais tu peux les créer avec plusieurs commentaires sur une ligne ou utiliser des triples guillemets, bien que ce dernier soit en réalité un littéral de chaîne multi-ligne qui ne s'exécute pas comme du code. Exemple :

# C'est un exemple de commentaire multi-lignes
# Chaque ligne commence par le symbole #
      

ou :

"""
C'est un littéral de chaîne multi-ligne qui peut être utilisé comme commentaire.
Python l'interprète comme une chaîne, mais ne fait rien avec cette chaîne 
si elle n'est pas assignée à une variable ou utilisée dans une expression.
"""
    
      

5.2 Pourquoi écrire des commentaires

L'utilisation de commentaires dans le code améliore sa lisibilité, facilite sa maintenance et sa mise à jour, et contribue à une collaboration plus efficace en équipe. Les commentaires doivent être brefs mais informatifs et à jour, afin de servir de documentation utile au code sans le surcharger d'informations inutiles.

Docstrings:

Ce sont des chaînes généralement placées au début des modules, classes, méthodes et fonctions pour décrire leur but. Elles sont encadrées de triples guillemets et peuvent être utilisées pour la génération automatique de documentation.

Exemple :

def add(a, b):
"""
    Fonction pour additionner deux nombres.
    :param a: premier terme
    :param b: deuxième terme
    :return: somme de a et b
    """
    return a + b

Dans le monde de la programmation, il arrive parfois que les développeurs ajoutent à leur code des commentaires qui servent non seulement d'explications, mais aussi à faire sourire. Voici quelques exemples de commentaires amusants que tu peux rencontrer dans le code :

Exemple 1

 

            # J'expliquerais ce qui se passe ici, mais même moi, je ne sais plus.
        

Exemple 2

 

    # Si ça ne marche pas, c'est la faute de quelqu'un d'autre.

Exemple 3

 

    # Je suis venu, j'ai vu, j'ai corrigé... et j'ai cassé.

Exemple 4

 

    # Quand j'ai écrit ça, seulement moi et Dieu savions comment ça marchait. 
    # Maintenant, Dieu seul le sait.

Ces commentaires peuvent ajouter de la légèreté et de l'humour au processus de développement, rendant la base de code moins monotone. Ils peuvent également servir de rappel que le développement de logiciels est un processus créatif et humain.

5.3 Commenter le code rapidement

Dans PyCharm, tu peux rapidement commenter ou décommenter le code en utilisant des raccourcis clavier. Pour cela, sélectionne les lignes de code que tu veux modifier et appuie sur Ctrl + / sur Windows (ou Cmd + / sur macOS). Cette combinaison de touches ajoute ou enlève le symbole de commentaire sur chaque ligne sélectionnée, rendant le processus rapide et efficace.