Les commentaires dans le code

Le Thu, 17 May 2007 20:18:21 +0200,

Le mien est "un _bon_ code se passe de commentaires" (C'est ma devise)
D'ailleurs, a mon epoque, les compilo optimisaient mieux un code non
optimisé, tres lisible, avec beaucoup de variables intermediaires,
qu'il supprimait lors de l'optimisation.
Il faut quand meme quelques commentaires indispensables, mais moins
y'en a, mieux on se porte.
Je considere que quelqu'un qui lit du C, comprend le C. Ou alors,
c'est un ouvrage didactique.

Je suis d'accord qu'un bon code se passe de commentaires *expliquant
le code lui-même (C ou autre)*. Par contre, il est souvent bienvenu de
commenter les algorithmes, pour que le lecteur ait une idée du but du
code avant de le lire.
Ça structure le code comme les titres de paragraphes d'un bouquin.

Par exemple quand, en Perl, j'utilise une transformée schwartzienne,
eh bien j'écris dans un commentaire « Schwartzian transform ». Ça évite
que le lecteur passe dix minutes à se dépêtrer avec cette série de
parenthèses et d'accolades et ça lui donne les mots-clefs pour chercher
dans les bouquins comment ça marche.
Par contre, ce serait contre-productif d'écrire « On applique une
transformée schwartzienne qui permet de trier en utilisant un cache
blah blah blah ».

De la même façon, quand on applique une formule mathématique non
triviale, ça vaut toujours le coup de noter une référence biblio à
côté, plutôt que de compter sur le nom de la variable ou de la fonction
pour éclairer le lecteur.


Quand on écrit du code, on peut aussi faire des manoeuvres qui
rendent le code plus lisible pour le lecteur très attentif, mais le
rendent aussi complètement opaque pour celui qui ne lirait qu'un bout
du fichier. Je pense par exemple à des décalages d'indices (pour faire
commencer un indice à 0 plutôt qu'à N).
Dans ce cas, je n'hésite pas à rappeler en cours de route que
« l'indice varie de 0 à p quand la valeur varie de N à p+N ».

Si vous achetez un livre ecrit en russe, vous ne vous attendez pas
trouver la traduction

Néanmoins, quand j'achète un livre en français (y compris du 20e
siècle), j'aime bien que des notes de bas de page me rappellent le
contexte historique ou me renvoient à d'autre textes qui permettent de
mieux comprendre le texte que je suis en train de lire.


--
Jérémy JUST <jeremy_just@netcourrier.com>

Le Thu, 17 May 2007 20:18:21 +0200, Zeyes <zeyeschezfree@nospam.fr>
écrivait dans fr.comp.os.linux.debats:

Ca me préoccupe, et je voudrais avoir votre avis.

Ce n'est pas vraiment pertinent au forum, mais si le but d'en parler
avec des gens qui partagent leur code, c'est peut-être un bon endroit
pour cela.

Le mien est "un _bon_ code se passe de commentaires" (C'est ma devise)

Cela dépend beaucoup du contexte. Si c'est un logiciel avec des
millions de lignes de code, la documentation devient essentielle.
Par exemple, certaines fonctions doivent apparaître dans un ordre
précis (ouvrir un fichier, lire ou écrire, fermer). Il faut parfois
initialiser certaines variables. De même, si le logiciel est court,
il y a peu de variables, donc le nom est explicite sans être très
long, mais si les variables sont nombreuses, c'est une autre histoire.
Il y a encore les machines à états qu'on risque d'utiliser, les
protocoles extérieurs (si on crée une page web, il faut tenir compte
de la séquence de sortie des balises, par exemple).

De même, si un projet est développé en équipe, il faut établir des
protocoles, travailler d'une façon à peu près normalisée, etc. Et
tout cela doit être documenté.

D'ailleurs, a mon epoque, les compilo optimisaient mieux un code non
optimisé, tres lisible, avec beaucoup de variables intermediaires, qu'il
supprimait lors de l'optimisation.
Il faut quand meme quelques commentaires indispensables, mais moins y'en
a, mieux on se porte.
Je considere que quelqu'un qui lit du C, comprend le C. Ou alors, c'est
un ouvrage didactique. Si vous achetez un livre ecrit en russe, vous ne
vous attendez pas trouver la traduction, sauf si c'est explicitement
ecrit sur la couverture, nan?
Voila, je lance le debat, opposé a ce qu'on apprend a l'ecole.

Dire que le sujet de mon mémoire, c'était un logiciel qui permet
d'auto-documenter ! Il présente les boucles et conditions sous forme
de diagrammes. Si j'utilise le présent, c'est que je m'en sers
encore, même si ma dernière compilation date de 1988 (en fait, je ne
sais pas où j'ai laissé le code source). Pour les intéressés, c'est
environ 50 000 lignes en ASM 8088 écrit pour DOS 2.0 et cela
fonctionne dans DOSEMU (mais c'est plus joli dans Windows avec la
bonne page graphique).

Pour en revenir au débat, je dirais que le code est suffisamment
documenté si on y retourne après plusieurs mois et qu'on s'y retrouve
tout de suite.


Denis

Zeyes <zeyeschezfree@nospam.fr> writes:

Je considere que quelqu'un qui lit du C, comprend le C. Ou alors, c'est
un ouvrage didactique. Si vous achetez un livre ecrit en russe, vous ne
vous attendez pas trouver la traduction, sauf si c'est explicitement
ecrit sur la couverture, nan?
Voila, je lance le debat, opposé a ce qu'on apprend a l'ecole.

Non. Tu oublies les amateurs (comme moi) dont un des agréments
essentiels du libre, c'est de pouvoir consulter le code et de
se divertir des ruses du programmeur. Les commentaires sont très
importants pour nous. Il n'y en a jamais assez.

Pour prendre des exemples transversaux, c'est la même chose
que lorsque tu lis de la poésie (va donc comprendre toutes
les subtilités pornos de P. Louys si tu n'as pas les
commentaires), lorsque tu regardes un film avec les commentaires
du metteur en scène, lorsque tu regardes un P. Klee avec
ses cours du Bauhaus etc.

L'accès à ce code et aux commentaires est presque l'argument
premier qui me fait préférer du libre à du proprio. L'utilité
des softs, ça reste toujours une petite enigme. Une calculatrice
ou un crayon et un papier, au fond, ça suffit souvent largement !

costaclt

Le Thu, 17 May 2007 20:18:21 +0200, Zeyes <zeyeschezfree@nospam.fr>
écrivait dans fr.comp.os.linux.debats:

Ca me préoccupe, et je voudrais avoir votre avis.

Ce n'est pas vraiment pertinent au forum, mais si le but d'en parler
avec des gens qui partagent leur code, c'est peut-être un bon endroit
pour cela.
Mais oui exactement: le code propriétaire, on ne le voit pas souvent...

sauf si on l'écrit soi-meme.

Le mien est "un _bon_ code se passe de commentaires" (C'est ma devise)

Cela dépend beaucoup du contexte. Si c'est un logiciel avec des
millions de lignes de code, la documentation devient essentielle.
Par exemple, certaines fonctions doivent apparaître dans un ordre
précis (ouvrir un fichier, lire ou écrire, fermer). Il faut parfois
initialiser certaines variables. De même, si le logiciel est court,
il y a peu de variables, donc le nom est explicite sans être très
long, mais si les variables sont nombreuses, c'est une autre histoire.
Il y a encore les machines à états qu'on risque d'utiliser, les
protocoles extérieurs (si on crée une page web, il faut tenir compte
de la séquence de sortie des balises, par exemple).

De même, si un projet est développé en équipe, il faut établir des
protocoles, travailler d'une façon à peu près normalisée, etc. Et
tout cela doit être documenté.
D'accord pour la documentation, je parlais des commentaires "embarques"

dans le code source.

D'ailleurs, a mon epoque, les compilo optimisaient mieux un code non
optimisé, tres lisible, avec beaucoup de variables intermediaires, qu'il
supprimait lors de l'optimisation.
Il faut quand meme quelques commentaires indispensables, mais moins y'en
a, mieux on se porte.
Je considere que quelqu'un qui lit du C, comprend le C. Ou alors, c'est
un ouvrage didactique. Si vous achetez un livre ecrit en russe, vous ne
vous attendez pas trouver la traduction, sauf si c'est explicitement
ecrit sur la couverture, nan?
Voila, je lance le debat, opposé a ce qu'on apprend a l'ecole.

Dire que le sujet de mon mémoire, c'était un logiciel qui permet
d'auto-documenter ! Il présente les boucles et conditions sous forme
de diagrammes. Si j'utilise le présent, c'est que je m'en sers
encore, même si ma dernière compilation date de 1988 (en fait, je ne
sais pas où j'ai laissé le code source). Pour les intéressés, c'est
environ 50 000 lignes en ASM 8088 écrit pour DOS 2.0 et cela
fonctionne dans DOSEMU (mais c'est plus joli dans Windows avec la
bonne page graphique).
Ca c'est bien, c'est aussi un autre inconvenient des commentaires: ils

ne sont pas verifiables/controlables mecaniquement avec le code. Il
m'est arrivé de perdre plusieurs jours parce que je me suis fié a un
commentaire incoherent avec le code qu'il commentait. La tu generes une
doc, qui est derivee du code.

Pour en revenir au débat, je dirais que le code est suffisamment
documenté si on y retourne après plusieurs mois et qu'on s'y retrouve
tout de suite.
Voui.

Bon, c'est plus un debat....
sniff.
Je cherchais a fortifier mon argumentaire a la lumiere d'oppositions
violentes.
Mais je suis content de trouver des sympathisants!

Denis

Zeyes

Le Thu, 17 May 2007 20:18:21 +0200,

Le mien est "un _bon_ code se passe de commentaires" (C'est ma devise)
D'ailleurs, a mon epoque, les compilo optimisaient mieux un code non
optimisé, tres lisible, avec beaucoup de variables intermediaires,
qu'il supprimait lors de l'optimisation.
Il faut quand meme quelques commentaires indispensables, mais moins
y'en a, mieux on se porte.
Je considere que quelqu'un qui lit du C, comprend le C. Ou alors,
c'est un ouvrage didactique.

Je suis d'accord qu'un bon code se passe de commentaires *expliquant
le code lui-même (C ou autre)*. Par contre, il est souvent bienvenu de
commenter les algorithmes, pour que le lecteur ait une idée du but du
code avant de le lire.
Ça structure le code comme les titres de paragraphes d'un bouquin.
D'accord

Par exemple quand, en Perl, j'utilise une transformée schwartzienne,
eh bien j'écris dans un commentaire « Schwartzian transform ». Ça évite
que le lecteur passe dix minutes à se dépêtrer avec cette série de
parenthèses et d'accolades et ça lui donne les mots-clefs pour chercher
dans les bouquins comment ça marche.
Par contre, ce serait contre-productif d'écrire « On applique une
transformée schwartzienne qui permet de trier en utilisant un cache
blah blah blah ».
Ce qui effectivement ne parlerait pas plus.... d'autant plus que je ne

sais pas ce que c'est.

De la même façon, quand on applique une formule mathématique non
triviale, ça vaut toujours le coup de noter une référence biblio à
côté, plutôt que de compter sur le nom de la variable ou de la fonction
pour éclairer le lecteur.
Voui, c'est ce a quoi je pensais en disant "quelques commentaires

indispensables"

Quand on écrit du code, on peut aussi faire des manoeuvres qui
rendent le code plus lisible pour le lecteur très attentif, mais le
rendent aussi complètement opaque pour celui qui ne lirait qu'un bout
du fichier. Je pense par exemple à des décalages d'indices (pour faire
commencer un indice à 0 plutôt qu'à N).
Dans ce cas, je n'hésite pas à rappeler en cours de route que
« l'indice varie de 0 à p quand la valeur varie de N à p+N ».

Si vous achetez un livre ecrit en russe, vous ne vous attendez pas
trouver la traduction

Néanmoins, quand j'achète un livre en français (y compris du 20e
siècle), j'aime bien que des notes de bas de page me rappellent le
contexte historique ou me renvoient à d'autre textes qui permettent de
mieux comprendre le texte que je suis en train de lire.

Bon, encore un sympatisant, j'aime.

Mais bon, il n'y a pas un prof d'informatique ici?
Parce que c'est encore ce que j'entends de jeunes informaticiens, avec
des ratios de commentaires (j'ai ouï 30%)

Le Thu, 17 May 2007 21:19:31 +0200, Zeyes a écrit :

Bon, encore un sympatisant, j'aime.
Mais bon, il n'y a pas un prof d'informatique ici?
Parce que c'est encore ce que j'entends de jeunes informaticiens, avec
des ratios de commentaires (j'ai ouï 30%)

Pour ma part j'explique en commentaire ce que fait une fonction, en
général avant de l'écrire :) Après effectivement je documente
seulement les éléments qui peuvent ne pas être évidents pour celui qui
relira (moi ou un autre).

--
Toutes les organisations ont leur règles, et les Femmes Algériennes
doivent avoir aussi leurs règles.
Aït Ahmed.

On 17 mai, 20:18, Zeyes <zeyeschezf...@nospam.fr> wrote:

Ca me préoccupe, et je voudrais avoir votre avis.
Le mien est "un _bon_ code se passe de commentaires" (C'est ma devise)
D'ailleurs, a mon epoque, les compilo optimisaient mieux un code non
optimisé, tres lisible, avec beaucoup de variables intermediaires, qu'il
supprimait lors de l'optimisation.

j'aimerais l'avis d'un connaisseur la dessus. Il me semble qu'au
debut une analyse lexicale est faite du code. Les DEFINE sont
remplacés à ce niveau là. Je pense que les commentaires sont
supprimés aussi. Testons, ça ne coute pas cher.
$ cat hello.c
#include <stdio.h>

int main()
{
printf("hellon");
}
$ gcc hello.c -o hello
$ vi hello.c
$ cat hello.c
/* et hop hop hop tralala */
#include <stdio.h>

/* plop plop plop */

int main()
{
/* et youplaboum */


printf("hellon");
}
$ gcc hello.c -o hello2
$ diff hello hello2
$

L'exemple est un peu limite, je ne suis pas programmeur, mais
je doute que les commentaires modifient un programme.

Il faut quand meme quelques commentaires indispensables, mais moins y'en
a, mieux on se porte.

La lecture de /usr/src/linux/Documentation/CodingStyle est
intéressante
(...)
First off, I'd suggest printing out a copy of the GNU coding
standards,
and NOT read it. Burn them, it's a great symbolic gesture.
(...)
Chapter 8: Commenting

Comments are good, but there is also a danger of over-commenting.
NEVER
try to explain HOW your code works in a comment: it's much better to
write the code so that the _working_ is obvious, and it's a waste of
time to explain badly written code.
(...)

0ui, je pense que commenter est necessaire. Mais comme
disait l'autre: la perfection, c'est quand il n'y a plus
rien a enlever, non pas quand il n'y a plus rien a ajouter.

octane@alinto.com, dans le message
<1179474882.061831.136210@y80g2000hsf.googlegroups.com>, a écrit :

j'aimerais l'avis d'un connaisseur la dessus. Il me semble qu'au
debut une analyse lexicale est faite du code. Les DEFINE sont
remplacés à ce niveau là. Je pense que les commentaires sont
supprimés aussi.

Oui, les commentaires ne changent strictement rien au code produit. Ce n'est
pas de ça dont il était question dans le paragraphe auquel tu réponds.

$ cat hello.c

Indente ton code, ça ira mieux.

$ gcc hello.c -o hello2

gcc -Wall -stdÉ9 -O2

Ca me préoccupe, et je voudrais avoir votre avis.
Le mien est "un _bon_ code se passe de commentaires" (C'est ma devise)

Si pour toi commenter un code, c'est écrire :
# ici on incrémente i
i++

alors d'accord, le bon code se passe de commentaire.
Mais un commentaire, c'est aussi écrire une phrase au début de la fonction,
ou d'un bloc de commandes expliquant rapidement l'utilité de cette fonction
ou ce bloc de commandes.

Même si le code est clair, quand tu cherches quelque chose dans un code
écrit par quelqu'un d'autre (ou par toi il y a longtemps), c'est toujours
plus rapide de survoler les commentaires que d'étudier le code. Au moment
où tu as trouvé ce que tu cherches, tu peux lire le code. Il faut commenter
le code.

--
Stéphane

Pour me répondre, traduire gratuit en anglais et virer le .invalid.
http://stef.carpentier.free.fr/

Ca me préoccupe, et je voudrais avoir votre avis.
Le mien est "un _bon_ code se passe de commentaires" (C'est ma devise)
D'ailleurs, a mon epoque, les compilo optimisaient mieux un code non
optimisé, tres lisible, avec beaucoup de variables intermediaires, qu'il
supprimait lors de l'optimisation.
Il faut quand meme quelques commentaires indispensables, mais moins y'en
a, mieux on se porte.
Je considere que quelqu'un qui lit du C, comprend le C. Ou alors, c'est
un ouvrage didactique. Si vous achetez un livre ecrit en russe, vous ne
vous attendez pas trouver la traduction, sauf si c'est explicitement
ecrit sur la couverture, nan?
Voila, je lance le debat, opposé a ce qu'on apprend a l'ecole.

Personnellement, je considère que le commentaire du code doit se limiter
essentiellement à une description rapides des fonctions, et à quelques
points délicats du code ou pour expliquer certains choix techniques.

Par exemple cette ligne:


long long int fibo (int n) {
return (long long int)floor( (n % 2) + (pow(phi, n))/sqrt(5.));
}

mérite des commentaires du style :
/* Calcule fibonacci d'une manière relativement subtile : formule de
Binet trafiquée par mes soins. */

/* Note : le choix du type double pour le calcul est discutable, car il
ne suffit pas pour avoir un long long int calculé exactement, mais pour
l'application ciblée la précision est suffisante */