Discussion :

[gl]

Il n'était pas trop possible ici d'avoir un gestionnaire de source commun entre le client et nous.

C'est dommage, car ça aurait probablement simplifier la vie de tout le monde, mais on ne fait pas toujours ce que l'on souhaite malheureusement.

Sinon pour en revenir au commentaire de versionning, comme je l'avais indiqué dans un autre message, c'est avant tout une question de contexte.

Dans mon contexte de travail, ces commentaires n'apporte rien et ont tendance à diluer inutilement le code.
Maintenant, il est possible de trouver différent cas de figure où ce type de commentaires est utile. La question qui se pose alors est celle de la durée de rétention de ces commentaires.

[Drumer67bts]

Je pense qu'il est nécessaire de commenter son code un minimum et qu'il soit commenté clairement.

J'ai dû une fois effectuer une mise à jour d'un programme qui n'avait pas été fait par moi. Il y avait effectivement des commentaires, mais ils n'étaient pas compréhensibles du tout. J'ai donc passé du temps à comprendre tout le code alors que si les commentaires avaient été clairs j'aurais gagné pas mal de temps.

Donc en effet, je pense que commenter son code permet une meilleure maintenance de celui-ci.

Concernant une meilleure lisibilité je dirais que oui s'il s'agit d'une partie de code complexe, et que non s'il s'agit d'une partie simple.

[hegros]

Comme expliqué précédemment, utilisé un nom d'indice purement technique autre que i apporte, de ce que j'ai pu constaté, plus de confusion qu'autre chose.

Il y a probablement d'autres expériences et à la lecture du code source plus besoin de faire la conversion i = un objet d'une collection =(dans notre cas) un objet graphique ou un objet technique ou pour reprendre ton idée un objet qui encapsulerait cette spécificité..Voir des For each obj in objs soit des objets à la place de simple integer avec une approche oo

On pourrait imaginer d'utiliser des noms plus long pour les bornes et l'indice qui intégrerait cette notion, mais au final on aurait probablement des identifieurs à rallonge qui posent autant de problèmes qu'ils n'en résolvent. Les noms à rallonge et les lignes trop longue pour rentrer sur un écran ne sont en effet pas très agréable à lire (à titre personnel, je préfère lire une ou deux lignes de commentaires en bon français ou en bon anglais qu'une suite de 50 caractères contigus représentant 5 ou 6 mots accolés entre eux sans respect de la moindre grammaire, mais je te l'accorde c'est là avant tout une question de goût).

Oui il y a déjà eu des remarques une ligne de programme c'est dans la 'norme', sans jouer sur les résolutions, 80 caractères disons pour un livre une 30-40 de mots. Mais quand tu dis sans la moindre grammaire ce n'est pas totalement vrai...

EltGraphicToDisplay est largement compréhensible et en décomposant Element Graphic To Display où est la faute ?

[1] Oui, car cette construction alambiqué est fortement inspiré d'un cas réel sur lequel j'étais tombé (en tant que mainteneur du code, je ne l'avais pas commis) où il n'y avait pas de commentaire. Je ne t'explique pas combien de temps j'ai mis à comprendre pourquoi il y avait ce code bancal (il faut dire que le projet en question ne brillait pas non plus par la qualité de la documentation, au contraire).

Oui effectivement avec le contexte cela se comprends mieux si tu passé en paramètre 0 il y avait un plantage ou cela fonctionnait en mode dégradé discret

[gl]

Il y a probablement d'autres expériences et à la lecture du code source plus besoin de faire la conversion i = un objet d'une collection =(dans notre cas) un objet graphique ou un objet technique ou pour reprendre ton idée un objet qui encapsulerait cette spécificité..Voir des For each obj in objs soit des objets à la place de simple integer avec une approche oo

Au temps pour moi, je parlais ici dans le cas de langage type C, ce qui était le cas de mon exemple.

Effectivement dans d'autre langage les possibilités offertes et les usages peuvent être différent.

Oui il y a déjà eu des remarques une ligne de programme c'est dans la 'norme', sans jouer sur les résolutions, 80 caractères disons pour un livre une 30-40 de mots. Mais quand tu dis sans la moindre grammaire ce n'est pas totalement vrai...

EltGraphicToDisplay est largement compréhensible et en décomposant Element Graphic To Display où est la faute ?

Dans ce cas là il n'y a pas de problème (enfin on pourrait ergoter sur l'utilisation de l'infinitif qui n'est pas super précis, mais bon). Mais est-ce généralisable ? Pour reprendre l'exemple classique, dans un jeu de dame, que fait la fonction PionMange() ?

Oui effectivement avec le contexte cela se comprends mieux si tu passé en paramètre 0 il y avait un plantage ou cela fonctionnait en mode dégradé discret

J'avoue que je ne m'en souviens pas, je n'ai même pas le souvenir d'avoir eu la curiosité de faire le test.

[souviron34]

pour reprendre ce que dit gl :

Pour reprendre l'exemple classique, dans un jeu de dame, que fait la fonction PionMange() ?

je dirais que :

EltGraphicToDisplay est largement compréhensible et en décomposant Element Graphic To Display où est la faute ?

n'est, à mon sens, pas la bonne manière de nommer l'objet ou la méthode..

Ce serait plus :


GraphicEltToDisplay

car je le comprend comme un nom d'objet, virtuellement graphique, qui sera affiché (éventuellement).

Ce qui, en langage "procédural" qui m'est familier, serait programmé correctement sous la forme :

GraphicItem (Elt est l'abréviation française de "élément", qui se dit "item" en anglais)

void DisplayItem ( GraphicItem *Item )
{
}

[MMB007]

non
par ce que des qu'on fait une modif
pouf!!!
le commentaire ne va plus avec

il faut avoir toujours une bonne doc et un commentaire sur svn serai plus adéquat

en tous c 'est ce que pense

[hegros]

void DisplayItem ( GraphicItem *Item )
{
}

Oui mais comme l'a précisé gl il ne lui été pas possible de modifier la signature et encore moins le nom de la fonction puisqu'elle fait partie d'une bibliothéque d'un fournisseur.


Le prototype de la fonction était et devait resté

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

void XXX_DisplayElt(int)

Pour reprendre l'exemple classique, dans un jeu de dame, que fait la fonction PionMange() ?

C'est bien une fonction pas une méthode d'une classe ? Ok.

A priori elle ne fait rien parce que sans aucun paramètre, à moins de taper dans des variables globales, elle ne devrait pas savoir faire grand chose...Tu n'as pas un exemple plus complet de ce que tu voulais souligner comme problèmatique

[aityahia]

Salut

les commentaires dans le code sont bien plus que recommandable, surtout dans des projets de grande envergure a développement collaboratif.

certes qu'il ne faut pas en abuser il faut mettre le bon commentaire au bon endroit, dans les grands projets open source la qualité des commentaires est parfois bien plus importante que celle du code lui même.

on parlant de commentaire je fait un petit passage sur l'importance de la documentation de code qui est malheureusement ignoré par la plupart des développeurs, pourtant d'une grande étendue elle permet entre autre la génération de doc, elle permet a votre IDE de fournir des descriptions sur vos class et fonctions ainsi que leurs paramètres.....


@+

[gl]

non
par ce que des qu'on fait une modif
pouf!!!
le commentaire ne va plus avec

il faut avoir toujours une bonne doc et un commentaire sur svn serai plus adéquat

J'ai toujours un peu de mal avec cet argument. Lorsque tu modifies le code, tu modifies le commentaires qui va avec. Je ne vois pas vraiment où est le problème.

Se rapporter à une documentation externe ne résout en rien ce problème puisque lorsqu'on fait un modification la documentation n'est plus à jour et qu'il faut également la modifier.

Quant aux commentaires de la gestion de conf, je ne vois pas en quoi ils peuvent remplacer les commentaires du code autres que les commentaires de versioning qui sont un cas particulier.

[gl]

C'est bien une fonction pas une méthode d'une classe ? Ok.

Ca ne change pas grand chose.

A priori elle ne fait rien parce que sans aucun paramètre, à moins de taper dans des variables globales, elle ne devrait pas savoir faire grand chose...Tu n'as pas un exemple plus complet de ce que tu voulais souligner comme problèmatique

Si tu préfères, tu peux utiliser boolean PionMange(Jeu* pjeu, Pion* ppion), ca ne change pas grand chose au problème.

L'utilisation d'un nom construit de la sorte ne permet pas toujours de faire passer toutes les subtilité (dans le cas présent forme passive/active et affirmation/question, mais ça peut être des notions temporelles, d'obligatoire/facultative ou autre).

Bien entendu dans la majorité des cas, il est possible de trouver un nom suffisamment parlant (et heureusement), mais malheureusement, il existe toujours des cas où l'interprétation du nom peut être ambigu (à moins d'avoir des noms à rallonge). Et généralement, connaissant le contexte il ne te semblera pas ambigu à toi et à l'équipe qui travaille sur le projet, mais plutôt au gars qui va utiliser ce code bien plus tard.

[bugsan]

Moi je m'arrange pour avoir des méthodes qui contiennent moins de 20 lignes de code, idéalement moins de 10 (pour ceux que ça ferait rire : allez jeter un œil à Spring). Et je mets tout le commentaire dans la javadoc. C'est très rare que je commente directement au milieu du code. Je trouve que ça réduit la visibilité.

[hegros]

les commentaires dans le code sont bien plus que recommandable, surtout dans des projets de grande envergure a développement collaboratif.

Vous pouvez simplement dire c'est plus que recommandable dans un modèle de développement open-source (il y a déjà eu un exemple avec un fichier du kernel linux) cela ne veut pas dire que c'est la ligne directrice pour tout les types de projets de développement logiciel.

certes qu'il ne faut pas en abuser il faut mettre le bon commentaire au bon endroit, dans les grands projets open source la qualité des commentaires est parfois bien plus importante que celle du code lui même.

C'est là tout le problème le bon commentaire au bon endroit car ce n'est ni une matière enseigné ni très discuté notamment par des livres qui en exposent tout le poids..

on parlant de commentaire je fait un petit passage sur l'importance de la documentation de code qui est malheureusement ignoré par la plupart des développeurs, pourtant d'une grande étendue elle permet entre autre la génération de doc, elle permet a votre IDE de fournir des descriptions sur vos class et fonctions ainsi que leurs paramètres.....

Les extra-commentaires JavaDoc peuvent très bien être écrit en dehors du code source (avec un outil de rétro-ingénierie par exemple) pour ensuite être généré et documenter les classes et les fonctions

[hegros]

<..>

Pour revenir sur les noms à rallonge retournons à ton premier exemple. Dans un certain sens la rallonge ne fais qu'expliciter un peu plus le code peut-être est-ce ce manque qui nous fais ajouter des commentaires ?


Version avec commentaire

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
6
/* Attention, la bibliothèque XXX indice ces éléments de 1 à n.
Le premier élément se trouve donc à l'indice 1 et non 0. */
for(i = 1; i <= N; i++)
{
   XXX_DisplayElt(i);
}

version sans commentaire*

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
for(i = START_INDEX_WITH_1_CONVENTION_LIB_XXX; i <= N; i++)
{
   XXX_DisplayElt(i);
}

Il pourrait y avoir d'autres versions surement meilleur qui annulerait le commentaire ou en plus fantaisie WARNING_START_INDEX_WITH_1_CONVENTION_LIB_XXX. Cela fait beaucoup de mot d'accord c'est une question de vocabulaire on pourrait toujours trouver plus petit et plus explicite

Cela ne me déplairait pas de sonder ces 2 versions parce qu'à mon sens c'est très explicite et le commentaire serait vraiment redondant et n'apporte ni plus de lisibilité que de maintenabilité


*rien n'empêche d'écrire un for sur 2 lignes c'est tout autant lisible et répandu.

[hegros]

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

FIRST_ELEMENT_STARTS_WITH_1_NO_0_CONVENTION_LIB_XXX

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
/* Attention, la bibliothèque XXX indice ces éléments de 1 à n.
Le premier élément se trouve donc à l'indice 1 et non 0. */

En même temps c'est un exemple exceptionnelle(dixit gl) parce qu'ici nous avons Sujet + verbe + complément quasi langage naturel...En gras la redondance/duplication.

Ca choque à ce point ?

[white_tentacle]

Ce que je retiens de cet exemple, c'est qu'une lib devrait fournir des itérateurs (ou similaire), plutôt que d'utiliser une convention implicite ou explicite...

J'ai eu le problème en migrant une appli vb6 vers vb.net, c'est tellement la merde avec les indices, qu'au final, j'ai tout passé en boucle for each pour être sûr de ne pas me planter.

[gl]

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

FIRST_ELEMENT_STARTS_WITH_1_NO_0_CONVENTION_LIB_XXX

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
/* Attention, la bibliothèque XXX indice ces éléments de 1 à n.
Le premier élément se trouve donc à l'indice 1 et non 0. */

Ca choque à ce point ?

Oui bien sur

Plus sérieusement, non ce n'est pas choquant juste lourd (enfin de mon point de vue), tu te traines un nom à rallonge qui n'est au final qu'une reprise du commentaire à la différence qu'il est difficile à mettre en forme et dans un langage non naturel (ce n'est pas de l'anglais ou du français correct).

Mais ma question est surtout, particulièrement si cette constante n'est utilisée qu'à cet endroit, qu'elle est la plus value de ce nom par rapport au commentaire initiale ?

Ce que je retiens de cet exemple, c'est qu'une lib devrait fournir des itérateurs (ou similaire), plutôt que d'utiliser une convention implicite ou explicite...

J'ai eu le problème en migrant une appli vb6 vers vb.net, c'est tellement la merde avec les indices, qu'au final, j'ai tout passé en boucle for each pour être sûr de ne pas me planter.

Pour les langages qui fournissent des itérateurs, des boucle for each ou d'autres mécanismes plus ou moins équivalent, c'est certes préférable (et pas uniquement d'un point de vue de l'expressivité d'ailleurs), malheureusement tous les langages ne le proposent, et même pour les langages qui le proposent encore faut-il que la bibliothèque le supporte. C'est un peu tout le problème de devoir utiliser des bibliothèques (framework, SDK ou autre d'ailleurs) externes pour lequel il n'y a pas d'alternative viable, tu es extrêmement dépendant de leur choix même lorsque ces choix sont visiblement mauvais.

[hegros]

Plus sérieusement, non ce n'est pas choquant juste lourd (enfin de mon point de vue), tu te traines un nom à rallonge qui n'est au final qu'une reprise du commentaire à la différence qu'il est difficile à mettre en forme et dans un langage non naturel (ce n'est pas de l'anglais ou du français correct).

ok de mon point de vue le commentaire est juste lourd pas choquant non enfin plus lourd qu'une constante

Mais ma question est surtout, particulièrement si cette constante n'est utilisée qu'à cet endroit, qu'elle est la plus value de ce nom par rapport au commentaire initiale ?

il faudrait déja trouver une plus value à ce commentaire n'adhérant pas du tout à ce type de commentaire qui est une spécification technique au final


l'avantage c'est qu'on comprends aussi bien avec une constante qu'avec le commentaire, mais avec moins de caractère, alors si en une ligne (compilable) il est possible d'exprimer sans ambiguité une obscurité de code alors pourquoi se prendre la tête d'en écrire 3 ?

autre avantage cela compacte le code source et notamment la fonction où se trouve cette portion de code puisque la constante serait plutot défini en tête de fichier soit directement on a l'information pas la peine de descendre au fin fond du source pour se le rappeler. Voilà pour la lisibilité.

De plus nous sommes parti sur un exemple exceptionnel soit on trouverait plus d'intérêt avec un exemple courant mais pour moi cela me semble bien suffisant..

[gl]

l'avantage c'est qu'on comprends aussi bien avec une constante qu'avec le commentaire, mais avec moins de caractère, alors si en une ligne (compilable) il est possible d'exprimer sans ambiguité une obscurité de code alors pourquoi se prendre la tête d'en écrire 3 ?

Car il est difficile avec un faible nom de mots d'exprimer certaines subtilités et précisions qu'il est simple de faire passer avec 2 ou 3 phrases bien tournées.

autre avantage cela compacte le code source et notamment la fonction où se trouve cette portion de code puisque la constante serait plutot défini en tête de fichier soit directement on a l'information pas la peine de descendre au fin fond du source pour se le rappeler. Voilà pour la lisibilité.

Oui et non.

C'est effectivement un argument pertinent. Cependant avec des fonctions courtes, la différence (et donc l'avantage) est assez ténue.

[hegros]

Car il est difficile avec un faible nom de mots d'exprimer certaines subtilités et précisions qu'il est simple de faire passer avec 2 ou 3 phrases bien tournées.

Ok...Les exemples aussi sont difficiles à trouver ne serait-ce qu'un exemple académique bien que je doute qu'il puisse en exister vraiment... Il n'y a même pas un article ou un tutorial la dessus mince !

C'est effectivement un argument pertinent. Cependant avec des fonctions courtes, la différence (et donc l'avantage) est assez ténue.

Si les fonctions sont courtes un bloc de commentaire aussi gros que la fonction en plein milieu au dessus ou en dessous cela fait tâche.

Arrêtons ici parce que si les commentaires étaient si utiles à la lisibilité ou à la maintenabilité il y aurait beaucoup plus d'exemples qui fuserait sur le post pour le démontrer et ce n'est pas le cas. Open-source ou pas.

[gl]

Arrêtons ici parce que si les commentaires étaient si utiles à la lisibilité ou à la maintenabilité il y aurait beaucoup plus d'exemples qui fuserait sur le post pour le démontrer et ce n'est pas le cas. Open-source ou pas.

Juste une petite précision pour déterminer. Comme je l'ai déjà dit [1], les cas où ils sont utiles ne sont pas fréquent du tout mais pas inexistant non plus.
Utile n'implique pas fréquent et rare n'implique pas inutile.


[1] Je n'avais peut être pas assez insisté sur ce point, mais ça reste des cas exceptionnels et donc forcément il ne sont pas légion (en dehors des commentaires d'en-tête de fonctions publiques, mais c'est un autre point).