J'aurais tendance à dire que ce sont deux choses différentes :
Les commentaires en Python et dans la Javadoc ont tendance à décrire l'API. L'objectif est de pouvoir récupérer la documentation d'une bibliothèque à partir de son code source, d'une part, et d'avoir la documentation sous les yeux lors de la programmation de la bibliothèque, d'autre part, non pas pour comprendre le code qu'on écrit, mais pour faciliter la synchronisation entre le code et sa documentation. Mais l'objectif final est de décrire l'API (cette fonction fait ça, celle là fait ceci…).
L'orientation des commentaires de la programmation lettrée est plus destinée à celui qui va lire le code, qu'à celui qui va l'utiliser : on ne se contente pas de dire ce que fait la fonction, mais on explique pourquoi, comment, tout ce qui n'est pas évident. Si j'écris un parser, la documentation « javadoc » va expliquer comment utiliser mon parser (appeler telle fonction pour tel résultat), et la documentation « lettrée » va expliquer le fonctionnement interne du parseur (quel algorithme, quelles exceptions…).
Dans ce morceau de code :
# Sys will be needed to acceed standard file descriptors (stderr, stdout, sdin). importsysdeferror(message):""""Display a message on the stderr"""# Don't forget to put a newline, as write, unlike print, will not append it for us.sys.stderr.write(message+"\n")
Le commentaire """ est l'équivalent de la javadoc, et les commentaires # sont l'équivalent de la programmation lettrée (quand à la pertinence des dit commentaires, essayez de trouver un meilleur exemple aussi court ;-)).
Pour un exemple en français de ce à quoi peut ressembler un programme littéraire, j'ai écrit celui-ci il y a trois ans. (soyez gentils avec ma connexion, c'est auto-hébergé)
Bon, mon style a beaucoup évolué depuis (c'est fou ce qu'on peut changer vite). Les morceaux de code sont conséquents, tout n'est pas dit (entre autre, une revue rapide du mode de fonctionnement du programme n'aurait pas été de trop), certains commentaires ont été écrits par captain obvious, il y a des passages pas très formels (lire : il y a des grossièretés), il n'y a pas de licence. Comme j'ai la flemme d'aller reprendre ce code dont je ne me sert plus du tout (puis bon, c'est un jouet, donc niveau motivation, si je l'utilise pas…), ces problèmes vont rester. À moins qu'un fou désire jouer avec. Dans ce cas, je ne dirais rien, mais il vaux mieux qu'il m'en informe, histoire que je fasse au moins l'effort de spécifier une licence, puis que je lui donne la source s'il ne l'a pas trouvé tout seul.
[^] # Re: Programmation lettrée, des retours d'expérience ?
Posté par daeldir . En réponse à la dépêche De tout, de rien, des bookmarks, du bla bla #10. Évalué à 4.
J'aurais tendance à dire que ce sont deux choses différentes :
Les commentaires en Python et dans la Javadoc ont tendance à décrire l'API. L'objectif est de pouvoir récupérer la documentation d'une bibliothèque à partir de son code source, d'une part, et d'avoir la documentation sous les yeux lors de la programmation de la bibliothèque, d'autre part, non pas pour comprendre le code qu'on écrit, mais pour faciliter la synchronisation entre le code et sa documentation. Mais l'objectif final est de décrire l'API (cette fonction fait ça, celle là fait ceci…).
L'orientation des commentaires de la programmation lettrée est plus destinée à celui qui va lire le code, qu'à celui qui va l'utiliser : on ne se contente pas de dire ce que fait la fonction, mais on explique pourquoi, comment, tout ce qui n'est pas évident. Si j'écris un parser, la documentation « javadoc » va expliquer comment utiliser mon parser (appeler telle fonction pour tel résultat), et la documentation « lettrée » va expliquer le fonctionnement interne du parseur (quel algorithme, quelles exceptions…).
Dans ce morceau de code :
Le commentaire
"""est l'équivalent de la javadoc, et les commentaires#sont l'équivalent de la programmation lettrée (quand à la pertinence des dit commentaires, essayez de trouver un meilleur exemple aussi court ;-)).Pour un exemple en français de ce à quoi peut ressembler un programme littéraire, j'ai écrit celui-ci il y a trois ans. (soyez gentils avec ma connexion, c'est auto-hébergé)
Bon, mon style a beaucoup évolué depuis (c'est fou ce qu'on peut changer vite). Les morceaux de code sont conséquents, tout n'est pas dit (entre autre, une revue rapide du mode de fonctionnement du programme n'aurait pas été de trop), certains commentaires ont été écrits par captain obvious, il y a des passages pas très formels (lire : il y a des grossièretés), il n'y a pas de licence. Comme j'ai la flemme d'aller reprendre ce code dont je ne me sert plus du tout (puis bon, c'est un jouet, donc niveau motivation, si je l'utilise pas…), ces problèmes vont rester. À moins qu'un fou désire jouer avec. Dans ce cas, je ne dirais rien, mais il vaux mieux qu'il m'en informe, histoire que je fasse au moins l'effort de spécifier une licence, puis que je lui donne la source s'il ne l'a pas trouvé tout seul.