Bonjour à tous.

Dans le livre "Apprendre à programmer avec python", G. Swinnen parle de l'importance des commentaires ("..." ou """...""") initiaux des classes et fonctions:

Dans notre exemple ultra-simplifié, cette ligne n'est rien d'autre
qu'un simple commentaire. (Par convention, si la première ligne suivant l'instruction class est
une chaîne de caractères, celle-ci sera considérée comme un commentaire et incorporée
automatiquement dans un dispositif de documentation des classes qui fait partie intégrante de
Python. Prenez donc l'habitude de toujours placer une chaîne décrivant la classe à cet endroit
Code : Sélectionner tout - Visualiser dans une fenêtre à part
1
2
3
4
5
class Ma_Classe():
    "ligne de commentaires"
 
def maFonction():
    "ligne de commentaires"
terminal python:
>>> from mon_fichier import Ma_classe
>>> help(Ma_Classe)

->
Code : Sélectionner tout - Visualiser dans une fenêtre à part
1
2
3
4
Help on class Ma_Classe in module fichier:
 
class Ma_Classe
 |  ligne de commentaires
Est-ce si utile que ça? Parce que j'aime bien utiliser des trucs du genre:

Code : Sélectionner tout - Visualiser dans une fenêtre à part
1
2
3
4
class Ma_Classe():
    #-------------------------
    # ligne de commentaires
    #-------------------------
Mais là les commentaires ne seront plus visibles dans la doc python.

A moins de faire ça:

Code : Sélectionner tout - Visualiser dans une fenêtre à part
1
2
3
4
5
6
class Ma_Classe():
    """
    #-------------------------
    # ligne de commentaires
    #-------------------------
    """
ou
Code : Sélectionner tout - Visualiser dans une fenêtre à part
1
2
3
4
class Ma_Classe():
    """#-------------------------
    # ligne de commentaires
    #---------------------------"""
Mais bon c'est moyen.

Vous vous demandez où je veux en venir?

Et bien j'étudie les possibilités offertes par les commentaires initiaux des classes et fonctions et j'ai l'impression que certaines choses m'échappent.

Par ex. est-ce que les commentaires initiaux (voir les ex ci-dessus) des classes et fonctions sont pris en comptes par les environnement de développement? Est-ce bien pratique dans ce cas? Serraient-ils intégrés avec tous les ex de codes fournis ci-dessus? Je ne sais pas encore car Eric4 et Monkey Studios ne sont pas facile à installer (librairies plus récentes que celles de mon système d'exploitation) et que je n'utilise pour le moment qu'un simple éditeur de texte (mais ça pourrait bientôt changer).

Je suis en train de coder un projet qui contiendra au moins 150 classes. Je n'ai pas envie de corriger tous les commentaires à la fin.

Votre avis?