Drozor

Que la documention soit generee a partir de commentaire dans le code est quelque chose qui s'est impose par le cote pratique mais ce n'est pas necessaire en soit. En realite il y a plein de choses que tu dois faire en dehors de cela, meme avec Doxygen, et qui ne sont pas sous forme de commentaires (ajout de liens ou schemas non generes depuis le code, documentation plus haut niveau, etc).

Les commentaire ne sont pas de la documentation et l'inverse est vraie egalement.

Si tu generes ta documentation a partir du 'code' (du fichier contenant egalement le code fonctionnel pour etre precis - pour le differencier de l'auto-completion qui va lire le code fonctionnel lui meme + eventuellement les annotations pour la doc) c'est bien justement pour obtenir un document independant de celui-ci.

Sauf que ce que tu lui as explique n'est pas important. Tu lui as dis de commenter tous les blocs, ce qui n'a pas de sens. Quand il montre un resultat passablement mauvais, tu lui dis que c'est bien mieux, ce qui n'est pas le cas.

Je lui conseille effectivement de ne pas commenter son code pour commenter son code. Tu lui aurais conseille de documenter pourquoi pas, et tu lui aurais fait les critiques sur le fait que ses commentaires etaient pour la plupart inutiles, j'aurais rien dit.

Comme je le disais, un bon code c'est un code avec le nombre minimal de commentaires. Le nombre minimal est celui qui fait que si je retire un commentaire, mon code devient plus difficile a lire / maintenir.

Un peu de lecture pour resumer. [EN]

Je suis d'accord avec toi Dominus Carnufex stop le débat !

Cela dit, je penses qu'on peut avoir un consensus sur le fait que c'est intéressant de commenter à minima son code non ?

Sans aller jusqu'à savoir si il faut générer une documentation et si il faut commenter chaque ligne, on doit pouvoir s'accorder sur le fait que commenter chaque bloc en indiquant son utilité est une bonne chose.

Après libre à Aze de se renseigner plus sur les bonnes pratiques en terme de commentaire et de voir à quel point il veut aller. Voici Aze un lien qui explique les bonnes pratiques de commentaires en php. Tu n'es pas obligée de tous commenter ainsi directement, mais au moins tu saura un peu comment ça fonctionne

Sans aller jusqu'à savoir si il faut générer une documentation

Il faut (a part peut etre des petits projets ou des trucs franchement amateurs).

et si il faut commenter chaque ligne, on doit pouvoir s'accorder sur le fait que commenter chaque bloc en indiquant son utilité est une bonne chose.

Non, c'est une mauvaise chose en regle generale.

Le consensus pratique serait plutot : documentation avant tout, commentaires la ou necessaire.

EDIT: J'ai retrouve ma citation.

As a general rule, the code explains to the computer and programmer what is being done; the comments explain to the programmer why it is being done.

Si un commentaire explique ce qui est fait et non pas pourquoi c'est fait, alors c'est un mauvais commentaire. Ensuite deuxieme question: est-ce qu'expliquer en francais ou anglais pourquoi je recupere la date au moment de l'inscription du membre, par exemple, est important ?

EDIT2: Le lien que tu cites va totalement dans mon sens:

Les commentaires en ligne peuvent être utilisés directement dans le code source pour indiquer des précisions techniques, à destination des développeurs qui devront lire ou reprendre le code, ou à soi même. Il peut s’agir d’un fonctionnement particulier, d’une précision sur telle utilisée plutôt que telle autre, etc. Il est important de les utiliser avec parcimonie tout en ayant bien conscience qu’ils sont parfois indispensables pour garder une trace des choix de codage.

Le reste c'est de la documentation.

Höd essaye de d'adapter à la personne au lieu d'arriver avec tes gros sabots… Aze est un débutant et il code en procédural. Comment tu veux qu'il documente des fonctions ou des classes vu qu'il n'y en à pas? Il peut juste commenter les blocs de code.

Dans un monde idéal il coderait en fonctionnel/objet, avec des commentaires de documentations et tout le tralala. Sauf qu'il débute.

Si il commente chaque bloc, ça sera déjà une énorme amélioration et ça rendra son code plus facile à comprendre et à maintenir. Sans refaire tout le code c'est ce qu'il peux faire de mieux en terme de commentaires… A moins que tu ai mieux à proposer ?

Le but est d'aider Aze à s'améliorer, pas de lui balancer des trucs du genre "quoi tu fais pas de tests ni de documentation ? Mais c'est null il faut faire ça tout de suite".

Ma remarque vise a lui faire comprendre ce qu'est un bon ou mauvais commentaire et surtout eviter de lui donner de mauvaises habitudes, ici par rapport a une surabondance de commentaires inutiles.

artragis lui a fait d'excellents commentaires, et cela ferait doublon. Mais effectivement, mieux que d'ajouter un commentaire sur un boucle pour dire qu'on itere sur un tableau par exemple, le premier conseil a lui donner serait de mieux organiser son code, et surtout d'avoir des noms de variables plus explicites.

Faudrait aussi me dire ou tu as lui que je lui ais dit "quoi tu fais pas de tests ni de documentation ? Mais c'est null il faut faire ça tout de suite". ou quelque chose du genre.

Et le paradigme n'a pas grand chose a voir la dedans. La documentation de fonction et de modules, cela se fait tres bien aussi. La preuve en paradigme fonctionnel.

Pas d'accord avec ça. Si y'a un truc que j'ai retenu de mes cours, c'est mon prof de C qui nous martelait "comments don't compile", autrement dit, y'a beau avoir marqué un truc dans les commentaires, c'est pas pour ça que c'est ce que va faire le bout de code.

Donc les commentaires pour éclairer un bout de code obscur, pourquoi pas, mais ça ne dispense pas de lire le code, voir ça peut induire en erreur si on lit trop vite et qu'on leur fait aveuglément confiance.

Quant à commenter chaque bout de code, y'a qu'à voir l'efficacité des systèmes automatiques de génération de documentation. C'est toujours super pertinant /s Je suis un fervant promoteur de la qualité des commentaires sur leur quantité.

EDIT: Mea culpa, j'ai répondu après la fin du débat. Je ne cherchais pas à relancer la discussion, mon post est HS :|

y'a beau avoir marqué un truc dans les commentaires, c'est pas pour ça que c'est ce que va faire le bout de code.

Je n'ai jamais le contraire

Le problème ici n'est pas de faire un débat sur la façon théorique de commenter ou non son code, mais d'aider un débutant ce qui est très différent. Son code n'est pas de très bonne qualité et est mal commenté ce qui pose problème. Si vous avez une pièce mal rangé et aucune étiquettes sur les objets le mieux est bien sur de bien ranger la pièce, et pourquoi pas de mettre des étiquettes. Mais en attendant de savoir bien ranger la pièce il peut être pertinent de mettre des étiquettes correctement pour mieux s'y retrouver et de ranger progressivement.

Vous voyez l'idée ? Si Aze commente mieux son code et l'expliquant, ça l'aidera à s'y retrouver et à naviguer dedans, tout en étant plus facile pour nous de comprendre ce qu'il veut faire. Ce qui ne veut pas dire qu'il ne faut pas en priorité améliorer la qualité du code, le nommage des variables etc.

Je doute que le dire "il faut re écrire tout ton code et faire des commentaires de documentation" soit super utile pour lui. Il faut bien faire par étape, d'abords éclaircir son code actuel avec des commentaires plus nombreux, bien placés et plus pertinent. Puis transformer ce code vers quelque chose de mieux

En tout cas c'est ma façon de voir les choses, en temps que débutant également je trouve ça bien plus réaliste que d'imaginer qu'il peut tout transformer d'un coup pour produire un code de qualité directement.

Surtout qu'il lui est impératif de rendre son code clair et lisible, de telle façon que des développeurs puissent le plus simplement possible contribuer à son projet

mais d'aider un débutant ce qui est très différent

Bah justement en lui expliquant la différence entre ce qui relève de la documentation et ce qui relève du commentaire dans le code. Sans lui dire "commente tous les blocs de code" sans distinction. C'est pas du tout compliqué à comprendre pour un débutant, et ça lui évite de s'infliger de faux dogmes ("je commente tout sans distinction") et mieux comprendre le pourquoi du comment un commentaire est intéressant.

Je suis plutôt d'accord avec Höd (et pas trop avec Dominus pour le coup, désolé :\ je pense que le "débat" mérite d'être lu par Aze pour le faire réfléchir à la question - et se poser les bonnes questions justement -). Les commentaires que Höd a pris pour exemple n'ont pas franchement lieu d'être quand la ligne s'exprime d'elle-même programmatiquement. Par contre, je pense que même un débutant devrait documenter son code fonctionnellement (que fait telle fonction, quels paramètres elle attend) surtout dans un langage comme PHP (encore plus en JS, amha), d'abord pour lui. Histoire qu'il soit un peu moins confronté au phénomène "I hate myself" ou mieux connu sous le nom de "Reprendre son code est un peu comme se battre contre une ancienne version de soi-même".

Tu as bien fait de montrer ton code Aze, tu vas vite te rendre compte à quel point ça va te faire progresser, et c'est un signe de maturité. Continue comme ça

je lis votre débat avec intérêt

Drozor à maintenant affiché 10 000 annonces !

Je n'ai pas eu le temps de coder beaucoup ces derniers jours, mais je vais me remettre au commitage en suivant vos conseils !

Sur combien de sites environ ?

25

400 annonces par sites ???

Non, je pense qu'il veut dire que ses annonces ont été affichées 10 000 fois sur 25 sites différents. Ce qui fait 400 pages vues par site.

Faut y interpréter comme a dit Phigger

Ha d'accord

Combien de clics sur ces 10.000 affichages ?

153 clics ça fait un taux de clic de 1.53%

Plutôt bon pour une régie monétisé (a ce que j'ai vu : je suis pas expert) mais sa me parait plus faible pour de la régie "P2P". Pour un début c'est bien mais il te faudrais créer des outils afin de rendre tes publicité plus ciblée et plus efficaces.

Ouais c'est ce que je pense aussi, je veut/vais mettre en place des catégories, mais j'attend de taper dans les 500 vues/jours minimum