commentaire initial des classes et fonctions

Bonjour à tous.

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

Citation:

---

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:

---

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:

---

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:

---

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:

---

1 2 3 4 5 6

class Ma_Classe(): """     #-------------------------     # ligne de commentaires     #-------------------------     """

---

ou

Code:

---

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?

les lignes entre """...""" sont des "chaînes de documentation" plutôt que des commentaires.
Tout commentaire commençant par # est ignoré par l'interpréteur Python.
les """...""" en début de fonction sont accessible par mafonction.__doc__ entres autres. Et tu n'as dans ce cas-là pas besoin de rajouter un # devant chaque ligne.

Donc c'est à toi de voir quelle valeur tu donnes à tes commentaires pour choisir l'une ou l'autre des représentations.

En tout cas, tout commentaire commençant par # est ignoré par l'interpréteur et ne sera jamais non plus utilisé par un IDE au contraire des docstrings.

Citation:

---

Envoyé par Guigui_

les """...""" en début de fonction sont accessible par mafonction.__doc__ entres autres.

---

On en apprend tous les jours. Je ne connaissais même pas la fonction:

Code:

---

def __doc__(self):

---

ni help(Ma_Classe.__doc__)

Merci. Et pour la documentation des classes dans un ide? Comment cela se présente? Est-ce que quelqu'un peut faire une capture d'écran du logiciel dans ce cas précis?

La fonction de classe def __doc__(self) a le mérite de bien gérer les accents. Ce qui n'est pas le cas de "" en début de classe. Quand je mets u"..." en début de classe puis
>>> help(Ma_Classe.__doc__)
l'interpréteur python me sort la doc de la fonction unicode...