Un commentaire, ca doit expliquer la raison d'etre d'un code illogique au 1er abordS (2 abords: metier et technique).
La plus grosse partie des "doc" doxygen & co est effectivement auto-generee, et donc inutile.souvent, ca decrit les parametres, qui ont deja un nom parlant.
Perso, je prefere decrire l'intention du bloc de code, ses pre-conditions et post-conditions, et si possible le faire en code, a coups d'assert() ou autres verifiables par le compilo.
Les intentions des parametres sont tres souvent dans leur nom apres tout.§
Pour les langages qui peuvent pas, c'est simple: je ne les utilise pas. Je considere que l'absence d'analyseur statique gratuit, libre et de qualite decente est un element de preuve qu'un langage est a eviter.
C et Cpp ont ca, java en a, pascal probablement.
Posté par yal (Mastodon) .
Évalué à 10.
Dernière modification le 17 décembre 2022 à 19:19.
De ce que je comprends de l’article, je ne suis pas du tout dans la cible à laquelle l’auteur s’adresse, n’étant ni dev et sachant qu’aucune des lignes de code que j’écris ne sera jamais lue par personne d ’autre que moi. Au contraire, je suis le genre à lire le code des autres pour tenter de comprendre ce que je pourrais faire dans le mien.
Pourtant, j’ai lu son article (c'était pas interdit). Et même s’il ne s’adresse pas à moi, je ne peux pas m’empêcher de réagir.
Ce qui suit est probablement totalement hors-sujet et dans aucun cas ce n’est à prendre comme une critique de ce qu’à écrit l’auteur. Au pire, c’est à prendre comme une réaction dans le choix de certains mots.
Mort aux commentaires inutiles ! Écrivez des commentaires pertinents !
Je comprends son agacement : ma moitié depuis près de 25 ans est développeuse (et pas trop nulle, autant que je sache). On bosse à domicile tous les deux, et je l’entends souvent râler sur des choses similaires.
Mais je me permets de signaler que « pertinent » et « inutile » ça ne veut absolument rien dire du tout hors du contexte de la rédaction dudit commentaire : il est écrit par qui et dans quelle intention, et pour qui ?
Débutant (et je pense le rester), je larde mes modestes petits scripts de ces commentaires « inutiles de débutants », dont il parle. Et aussi mes fichiers de configuration.
Je comprends qu’ils soient inutiles pour l’auteur (comme ils font sourire ma douce et tendre quand elle jette un œil sur mes prouesses informatiques), mais ils sont essentiels pour moi. Parce que je n’y touche pas tous les jours, je veux pouvoir relire et comprendre ce que j’ai écrit dans ces langues étrangères que sont Bash, Python, Lisp, etc. que ce soit dans trois mois, ou dans trois ans.
Et pour y arriver, je fais la chose la plus efficace que je connaisse : je les « paraphrase », comme dit l'auteur: je les traduits dans des langues que je pratique plus couramment, comme le français et surtout l’anglais (car j’ai souvent lu et entendu que c’est MAL, TRÈS TRÈS MAL de rédiger ses commentaires en français dans du code ;).
De même, quand je lis :
Donc, si vous écrivez ce genre de commentaire, non seulement vous perdez du temps,
J’ai juste envie de répondre : Heu… Non ?
Ou alors, si la seule légitimité de toute acte informatique est « de ne pas perdre de temps », j’ai envie de dire que personne, moi le premier, ne devrait « passer à GNU/Linux ».
Devoir tout réapprendre, s’embêter à chercher une machine bien supportée et choisir et installer un OS qui nous convienne (alors qu’il suffit d’entrer dans un Apple Store pour en ressortir avec une machine qu’il suffit de démarrer pour bosser dessus). Puis, il faut trouver les apps alternatives à celles qu’on connaît pourtant déjà si bien, et apprendre à les utiliser correctement (alors qu’il suffit de payer/se connecter à son compte pour retrouver en quelques instants Photoshop, Illustrator et Word sur son nouveau Mac)… C’est beaucoup de temps perdu. Et se casser le popotin à faire marcher sous nunux des périphs qui marchent parfaitement (façon de parler, hein) sur Windows ou sur Mac ? C’est encore plus de temps perdu, non ?
Je bossais plus vite sur un Mac (par exemple, je préparais mes ebooks bien plus rapidement avec un outil comme Vellum, qui moulinait mes fichiers Word et me sortait exactement et en un clic ce qu’il fallait comme fichiers pour donner le sourire à toutes les grosses boutiques de ventes d’ebooks ce qui, vu le temps gagné, suffisait largement à légitimer son prix à mes yeux). J’y arrivais donc mieux sur un Mac que je n’y arriverais jamais sur GNU/Linux avec LO et ses extensions Epub, ou avec pandoc et Markdown ou Markdown et Crowbook, ou Emacs et Org, ou avec LaTeX (hum, surtout pour faire des ebooks).
Quelqu’un de plus malin que moi y arriverait certainement. Pas moi. Mais c'est pas un souci.
Car ce n’est pas pour être plus efficace que je me suis éloigné de l’univers Apple pour aller vers GNU/Linux. C’est pour respirer plus librement. Pour me sentir chez moi sur mon ordinateur.
Et pour ça, pour ne sentir chez moi et pour cette liberté que m'offre le logiciel libre et pour son absence de traçage, je suis plus que ravi de perdre un peu de mon temps… y compris à écrire des commentaires inutiles, dans mon code informatique et peut être aussi — je laisse chacun en décider — ici ;)
Toutes mes excuses pour ce long hors-sujet.
C’est juste que le focus sur l’efficacité (comme le ton du billet, qui se veut un peu provocateur) me semble toujours dangereusement réducteur, et toujours aussi peu accueillant aux non-efficaces par définition que sont les débutants.
Ton commentaire est pertinent de mon point de vue, le cas que tu décris (celui du débutant qui a besoin de commentaires « évidents » pour s'aider) est un cas réel, et oui, dans ce cas c'est logique (et parfois nécessaire) d'écrire des commentaires qui paraissent triviaux. Le cas est simplement hors du propos du billet, qui ne concerne que ce qui respecte la directive en en-tête : « Les utilisateurs de votre code, savent lire le code ».
Donc, en tant que débutant, tu n'as pas à te sentir concerné par ce billet. Au contraire : si mettre des commentaires, quels qu'ils soient, te permettent de mieux comprendre ce que tu fais et de t'y retrouver quelques mois plus tard, vas-y.
Idem pour le code que qui est fait pour soi et qui ne sera jamais partagé, là tu fais bien ce que tu veux (même si tu violes toutes les « bonnes pratiques » du langage), c'est ton problème et ne concerne que toi.
Mon billet concerne les cas de travail en équipe, en particulier dans un contexte professionnel (ou assimilé, dans le sens ou les acteurs ont normalement tous les compétences pour lire du code). Là, même s'il y a quelques « débutants » dans l'équipe, tout le monde est censé avoir un niveau minimum et surtout devenir rapidement opérationnel, au point de ne plus avoir besoin de commentaires tautologiques. Le billet part aussi du principe que, dans les faits, personne n'aime écrire des commentaires, et que c'est d'autant plus dommage de perdre du temps dans un truc qui n'a aucune valeur ajoutée.
Bon l'article,le énième sur le sujet , en lui même n'as pas beaucoup d’intérêt : les exemples de commentaires inutiles sont caricaturaux et aucun exemple de commentaire utile.
Au risque de te surprendre, les deux exemples de commentaires inutiles sont des exemples réels de code en production… Oui, on trouve des gens qui trouvent encore utile de rédiger de tels commentaires (ou de les auto-générer), et pire, de demander à leurs collègues de faire de même.
Quant aux exemples de commentaires « utiles », en fait c'est difficile à donner sans devenir très verbeux. Mais si tu as des exemples à fournir, je serais heureux de les intégrer au billet.
N'importe quel commentaire qui decrit l'intention d'une ligne de code avec des expressions mathematiques pointues ou d'arithmetique binaire me semble qualifier pour les commentaires non verbeux utile. Parce que ces choses sont generalement obscures (plus que le langage natif en tout cas), meme a ceux qui decalent et masquent courramment des bits, et j'imagine que c'est la meme pour les matheux, voire une formule un peu evoluee ne dois pas necessairement leur dire a quoi elle sert.
Autre type de commentaire court et utile: les patchs d'historique et certains trucs a cause d'une regle metier qu'il faut modifier en vitesse. Quand tu as une vieille base de code pas forcement bien codee (donc souvent peu ou pas documentee) ou juste un n+1 qui demande un truc sorti de derriere les fagots pour hier, parfois il est bon d'expliquer l'interet d'une ligne qui semble triviale, stupide ou inutile au 1er abord.
Chaque commentaire commence d'ailleurs par # pour ressembler à un commentaire shell.
// commentaire méta sur les commentaires
<!-- la ligne ci-dessus documente cette partie -->
* note: en Fortran on ferait différemment
c ou autrement
; fin du commentaire
# je trouve les commentaires peu utiles. Par contrec la doc est trop absente!
Posté par freem . Évalué à 3.
Un commentaire, ca doit expliquer la raison d'etre d'un code illogique au 1er abordS (2 abords: metier et technique).
La plus grosse partie des "doc" doxygen & co est effectivement auto-generee, et donc inutile.souvent, ca decrit les parametres, qui ont deja un nom parlant.
Perso, je prefere decrire l'intention du bloc de code, ses pre-conditions et post-conditions, et si possible le faire en code, a coups d'assert() ou autres verifiables par le compilo.
Les intentions des parametres sont tres souvent dans leur nom apres tout.§
Pour les langages qui peuvent pas, c'est simple: je ne les utilise pas. Je considere que l'absence d'analyseur statique gratuit, libre et de qualite decente est un element de preuve qu'un langage est a eviter.
C et Cpp ont ca, java en a, pascal probablement.
# Heu...
Posté par yal (Mastodon) . Évalué à 10. Dernière modification le 17 décembre 2022 à 19:19.
De ce que je comprends de l’article, je ne suis pas du tout dans la cible à laquelle l’auteur s’adresse, n’étant ni dev et sachant qu’aucune des lignes de code que j’écris ne sera jamais lue par personne d ’autre que moi. Au contraire, je suis le genre à lire le code des autres pour tenter de comprendre ce que je pourrais faire dans le mien.
Pourtant, j’ai lu son article (c'était pas interdit). Et même s’il ne s’adresse pas à moi, je ne peux pas m’empêcher de réagir.
Ce qui suit est probablement totalement hors-sujet et dans aucun cas ce n’est à prendre comme une critique de ce qu’à écrit l’auteur. Au pire, c’est à prendre comme une réaction dans le choix de certains mots.
Je comprends son agacement : ma moitié depuis près de 25 ans est développeuse (et pas trop nulle, autant que je sache). On bosse à domicile tous les deux, et je l’entends souvent râler sur des choses similaires.
Mais je me permets de signaler que « pertinent » et « inutile » ça ne veut absolument rien dire du tout hors du contexte de la rédaction dudit commentaire : il est écrit par qui et dans quelle intention, et pour qui ?
Débutant (et je pense le rester), je larde mes modestes petits scripts de ces commentaires « inutiles de débutants », dont il parle. Et aussi mes fichiers de configuration.
Je comprends qu’ils soient inutiles pour l’auteur (comme ils font sourire ma douce et tendre quand elle jette un œil sur mes prouesses informatiques), mais ils sont essentiels pour moi. Parce que je n’y touche pas tous les jours, je veux pouvoir relire et comprendre ce que j’ai écrit dans ces langues étrangères que sont Bash, Python, Lisp, etc. que ce soit dans trois mois, ou dans trois ans.
Et pour y arriver, je fais la chose la plus efficace que je connaisse : je les « paraphrase », comme dit l'auteur: je les traduits dans des langues que je pratique plus couramment, comme le français et surtout l’anglais (car j’ai souvent lu et entendu que c’est MAL, TRÈS TRÈS MAL de rédiger ses commentaires en français dans du code ;).
De même, quand je lis :
J’ai juste envie de répondre : Heu… Non ?
Ou alors, si la seule légitimité de toute acte informatique est « de ne pas perdre de temps », j’ai envie de dire que personne, moi le premier, ne devrait « passer à GNU/Linux ».
Devoir tout réapprendre, s’embêter à chercher une machine bien supportée et choisir et installer un OS qui nous convienne (alors qu’il suffit d’entrer dans un Apple Store pour en ressortir avec une machine qu’il suffit de démarrer pour bosser dessus). Puis, il faut trouver les apps alternatives à celles qu’on connaît pourtant déjà si bien, et apprendre à les utiliser correctement (alors qu’il suffit de payer/se connecter à son compte pour retrouver en quelques instants Photoshop, Illustrator et Word sur son nouveau Mac)… C’est beaucoup de temps perdu. Et se casser le popotin à faire marcher sous nunux des périphs qui marchent parfaitement (façon de parler, hein) sur Windows ou sur Mac ? C’est encore plus de temps perdu, non ?
Je bossais plus vite sur un Mac (par exemple, je préparais mes ebooks bien plus rapidement avec un outil comme Vellum, qui moulinait mes fichiers Word et me sortait exactement et en un clic ce qu’il fallait comme fichiers pour donner le sourire à toutes les grosses boutiques de ventes d’ebooks ce qui, vu le temps gagné, suffisait largement à légitimer son prix à mes yeux). J’y arrivais donc mieux sur un Mac que je n’y arriverais jamais sur GNU/Linux avec LO et ses extensions Epub, ou avec pandoc et Markdown ou Markdown et Crowbook, ou Emacs et Org, ou avec LaTeX (hum, surtout pour faire des ebooks).
Quelqu’un de plus malin que moi y arriverait certainement. Pas moi. Mais c'est pas un souci.
Car ce n’est pas pour être plus efficace que je me suis éloigné de l’univers Apple pour aller vers GNU/Linux. C’est pour respirer plus librement. Pour me sentir chez moi sur mon ordinateur.
Et pour ça, pour ne sentir chez moi et pour cette liberté que m'offre le logiciel libre et pour son absence de traçage, je suis plus que ravi de perdre un peu de mon temps… y compris à écrire des commentaires inutiles, dans mon code informatique et peut être aussi — je laisse chacun en décider — ici ;)
Toutes mes excuses pour ce long hors-sujet.
C’est juste que le focus sur l’efficacité (comme le ton du billet, qui se veut un peu provocateur) me semble toujours dangereusement réducteur, et toujours aussi peu accueillant aux non-efficaces par définition que sont les débutants.
[^] # Commentaire supprimé
Posté par Anonyme . Évalué à 2.
Ce commentaire a été supprimé par l’équipe de modération.
[^] # Re: Heu...
Posté par SpaceFox (site web personnel, Mastodon) . Évalué à 6. Dernière modification le 17 décembre 2022 à 20:23.
Coucou, c'est l'auteur du billet ici :)
Ton commentaire est pertinent de mon point de vue, le cas que tu décris (celui du débutant qui a besoin de commentaires « évidents » pour s'aider) est un cas réel, et oui, dans ce cas c'est logique (et parfois nécessaire) d'écrire des commentaires qui paraissent triviaux. Le cas est simplement hors du propos du billet, qui ne concerne que ce qui respecte la directive en en-tête : « Les utilisateurs de votre code, savent lire le code ».
Donc, en tant que débutant, tu n'as pas à te sentir concerné par ce billet. Au contraire : si mettre des commentaires, quels qu'ils soient, te permettent de mieux comprendre ce que tu fais et de t'y retrouver quelques mois plus tard, vas-y.
Idem pour le code que qui est fait pour soi et qui ne sera jamais partagé, là tu fais bien ce que tu veux (même si tu violes toutes les « bonnes pratiques » du langage), c'est ton problème et ne concerne que toi.
Mon billet concerne les cas de travail en équipe, en particulier dans un contexte professionnel (ou assimilé, dans le sens ou les acteurs ont normalement tous les compétences pour lire du code). Là, même s'il y a quelques « débutants » dans l'équipe, tout le monde est censé avoir un niveau minimum et surtout devenir rapidement opérationnel, au point de ne plus avoir besoin de commentaires tautologiques. Le billet part aussi du principe que, dans les faits, personne n'aime écrire des commentaires, et que c'est d'autant plus dommage de perdre du temps dans un truc qui n'a aucune valeur ajoutée.
Au risque de te surprendre, les deux exemples de commentaires inutiles sont des exemples réels de code en production… Oui, on trouve des gens qui trouvent encore utile de rédiger de tels commentaires (ou de les auto-générer), et pire, de demander à leurs collègues de faire de même.
Quant aux exemples de commentaires « utiles », en fait c'est difficile à donner sans devenir très verbeux. Mais si tu as des exemples à fournir, je serais heureux de les intégrer au billet.
La connaissance libre : https://zestedesavoir.com
[^] # Re: Heu...
Posté par freem . Évalué à 4.
N'importe quel commentaire qui decrit l'intention d'une ligne de code avec des expressions mathematiques pointues ou d'arithmetique binaire me semble qualifier pour les commentaires non verbeux utile. Parce que ces choses sont generalement obscures (plus que le langage natif en tout cas), meme a ceux qui decalent et masquent courramment des bits, et j'imagine que c'est la meme pour les matheux, voire une formule un peu evoluee ne dois pas necessairement leur dire a quoi elle sert.
Autre type de commentaire court et utile: les patchs d'historique et certains trucs a cause d'une regle metier qu'il faut modifier en vitesse. Quand tu as une vieille base de code pas forcement bien codee (donc souvent peu ou pas documentee) ou juste un n+1 qui demande un truc sorti de derriere les fagots pour hier, parfois il est bon d'expliquer l'interet d'une ligne qui semble triviale, stupide ou inutile au 1er abord.
# Linuxfr ?
Posté par pamputt . Évalué à 10.
Est ce que ça s'applique aussi aux commentaires sur Linuxfr ?
[^] # Re: Linuxfr ?
Posté par Yth (Mastodon) . Évalué à 2.
On t'as dis d'aller écrire de la doc ! Allez, du vent…
Pfff.
[^] # Re: Linuxfr ?
Posté par Benoît Sibaud (site web personnel) . Évalué à 5.
Chaque commentaire commence d'ailleurs par # pour ressembler à un commentaire shell.
// commentaire méta sur les commentaires
<!-- la ligne ci-dessus documente cette partie -->
* note: en Fortran on ferait différemment
c ou autrement
; fin du commentaire
Suivre le flux des commentaires
Note : les commentaires appartiennent à celles et ceux qui les ont postés. Nous n’en sommes pas responsables.