Docstrings vs Commentaires
Je suis un peu confus sur la différence entre les docstrings et les commentaires en python.
Dans ma classe, mon professeur a introduit quelque chose connu sous le nom de `` recette de conception '', un ensemble d'étapes qui nous aideraient soi-disant les étudiants à mieux tracer et organiser notre codage en Python. D'après ce que je comprends, ce qui suit est un exemple des étapes que nous suivons - appelez donc recette de conception (les trucs dans les citations):
def term_work_mark(a0_mark, a1_mark, a2_mark, ex_mark, midterm_mark):
''' (float, float, float, float, float) -> float
Takes your marks on a0_mark, a1_mark, a2_mark, ex_mark and midterm_mark,
calculates their respective weight contributions and sums these
contributions to deliver your overall term mark out of a maximum of 55 (This
is because the exam mark is not taken account of in this function)
>>>term_work_mark(5, 5, 5, 5, 5)
11.8
>>>term_work_mark(0, 0, 0, 0, 0)
0.0
'''
a0_component = contribution(a0_mark, a0_max_mark, a0_weight)
a1_component = contribution(a1_mark, a1_max_mark, a1_weight)
a2_component = contribution(a2_mark, a2_max_mark, a2_weight)
ex_component = contribution(ex_mark, exercises_max_mark,exercises_weight)
mid_component = contribution(midterm_mark, midterm_max_mark, midterm_weight)
return (a0_component + a1_component + a2_component + ex_component +
mid_component)
Autant que je sache, il s'agit essentiellement d'une docstring, et dans notre version d'une docstring, elle doit inclure trois choses: une description, des exemples de ce que votre fonction devrait faire si vous la saisissez dans le python Shell et un "contrat de type", une section qui vous montre quels types vous entrez et quels types la fonction renverra.
Maintenant, tout cela est bien et fait, mais nos missions nous obligent à avoir également des commentaires qui expliquent la nature de nos fonctions, en utilisant le symbole '#'.
Donc, ma question est, n'ai-je pas déjà expliqué ce que ma fonction fera dans la section description de la docstring? Quel est l'intérêt d'ajouter des commentaires si je dis essentiellement la même chose au lecteur?
Il semble que votre professeur soit un fan de How to Design Programs;)
Je considérerais cela comme une écriture pour deux publics différents qui ne se chevauchent pas toujours.
Il y a d'abord les docstrings; ce sont pour les personnes qui vont utiliser votre code sans avoir besoin ou vouloir savoir comment cela fonctionne. Les docstrings peuvent être transformés en documentation réelle. Considérez la Python officielle - ce qui est disponible dans chaque bibliothèque et comment l'utiliser, aucun détail d'implémentation (à moins qu'ils ne soient directement liés à l'utilisation)
Deuxièmement, il y a des commentaires dans le code; ce sont pour expliquer ce qui se passe aux gens (généralement vous!) qui veulent étendre le code. Ceux-ci ne seront normalement pas transformés en documentation car ils concernent vraiment le code lui-même plutôt que son utilisation. Maintenant, il y a autant d'opinions sur ce qui fait de bons commentaires (ou leur absence) qu'il y a de programmeurs. Mes règles de base personnelles pour ajouter des commentaires sont d'expliquer:
- Parties du code nécessairement complexes. (L'optimisation me vient à l'esprit)
- Solutions de contournement pour le code que vous n'avez pas le contrôle, qui pourrait autrement sembler illogique
- J'admets aussi les TODO, bien que j'essaye de garder ça au minimum
- Où j'ai fait le choix d'un algorithme plus simple où une option plus performante (mais plus complexe) peut aller si les performances dans cette section deviennent plus tard critiques
Étant donné que vous codez dans un cadre universitaire et que votre conférencier semble verbeux, je dirais simplement rouler avec. Utilisez des commentaires de code pour expliquer comment vous faites ce que vous dites que vous faites dans la recette de conception.
Tout d'abord, pour mettre en forme vos messages, vous pouvez utiliser les options d'aide au-dessus de la zone de texte dans laquelle vous tapez votre message.
Et à propos des commentaires et des chaînes de doc, la chaîne de doc est là pour expliquer l'utilisation globale et les informations de base des méthodes. D'autre part, les commentaires sont destinés à donner des informations spécifiques sur les blocs ou les lignes, #TODO est utilisé pour vous rappeler ce que vous voulez faire à l'avenir, la définition des variables, etc. Soit dit en passant, dans IDLE, la chaîne de documentation s'affiche sous forme d'infobulle lorsque vous survolez le nom de la méthode.
Citant cette page http://www.pythonforbeginners.com/basics/python-docstrings/
Les chaînes de documentation Python (ou docstrings) fournissent un moyen pratique d'associer la documentation aux modules, fonctions, classes et méthodes Python).
La documentation d'un objet est définie en incluant une constante de chaîne comme première instruction dans la définition de l'objet.
Il est spécifié dans le code source qui est utilisé, comme un commentaire, pour documenter un segment spécifique de code.
Contrairement aux commentaires de code source conventionnels, la docstring doit décrire ce que fait la fonction, pas comment.
Toutes les fonctions doivent avoir une docstring
Cela permet au programme d'inspecter ces commentaires au moment de l'exécution, par exemple en tant que système d'aide interactif ou en tant que métadonnées.
Les docstrings sont accessibles par l'attribut __ doc __ sur les objets.
- Les docstrings sont accessibles via un programme (
__doc__) où les commentaires en ligne ne sont pas accessibles. - Les systèmes d'aide interactifs comme dans bpython et IPython peuvent utiliser des docstrings pour afficher la docsting pendant le développement. Pour que vous n'ayez pas à visiter le programme à chaque fois.
Je crois qu'il vaut la peine de mentionner ce que dit PEP8, je veux dire, le concept pur.
Docstrings
Les conventions pour écrire de bonnes chaînes de documentation (a.k.a. "docstrings") sont immortalisées dans PEP 257.
Écrivez des docstrings pour tous les modules, fonctions, classes et méthodes publiques. Les docstrings ne sont pas nécessaires pour les méthodes non publiques, mais vous devriez avoir un commentaire qui décrit ce que fait la méthode. Ce commentaire devrait apparaître après la ligne def.
PEP 257 décrit de bonnes conventions de docstring. Notez que le plus important, le "" "qui termine une chaîne de documentation multiligne doit être sur une ligne par lui-même, par exemple:
"""Return a foobang Optional plotz says to frobnicate the bizbaz first. """Pour une docstrings de doublure, veuillez conserver la fermeture "" "sur la même ligne.
Commentaires
Bloquer les commentaires
S'appliquent généralement à tout ou partie du code qui les suit et sont mis en retrait au même niveau que ce code. Chaque ligne d'un commentaire de bloc commence par un # et un seul espace (sauf s'il s'agit de texte en retrait à l'intérieur du commentaire).
Les paragraphes à l'intérieur d'un commentaire de bloc sont séparés par une ligne contenant un seul #.
Commentaires en ligne
Utilisez les commentaires en ligne avec parcimonie.
Un commentaire en ligne est un commentaire sur la même ligne qu'une instruction. Les commentaires en ligne doivent être séparés d'au moins deux espaces de l'instruction. Ils doivent commencer par un # et un seul espace.
Les commentaires en ligne sont inutiles et en fait distrayants s'ils indiquent l'évidence.
Ne faites pas cela:
x = x + 1 # Incrément x
Mais parfois, cela est utile:
x = x + 1 # Compenser la bordure