Discussion :

[Teaniel]

Bonjour,

Désolé pour la réponse tardive, hier matin j'en ai commencé une, et j'ai malencontreusement fermé le navigateur au lieu de poster... (début de dmla? )
Ce matin j'ai voulu reprendre le fil, et je n'ai pas pu recherger le brouillon. Les sauvegardes automatiques ne sont elles pas conservées un temps?

Ceci étant, merci, vraiment pour ton aide.
J'ai évidemment commencé par télécharger ton code, et à le regarder, et à chercher à le comprendre.
Je reviendrai vers toi (ici, je veux dire ) avec les questions auxquelles je n'aurai pas trouvé de réponse.

Y a pas de quoi être vexé!!!

Oublie pas

(:humour: évidemment!)

, c'était simplement une façon de marquer mon admiration.

Je me permets de revenir un peu en arrière :

En dehors des cartouches et d'éventuels commentaires didactiques (pour ceux qui écrivent des cours et des tutos), les commentaires sont à bannir du code... Ca tombe bien, non

J'espère que j'interprète bien, mais je ne suis pas vraiment d'accord : J'aurais bien pris quelques lignes d'explication dans mon code pour déverminer plus facilement les fonctions d'E/S de mon programme, et quelques autres que je vais avoir à reprendre. Tant que tu es plongé dans ton trip, tout est toujours clair. Mais laisse reposer quelques mois, et tu te retrouves à te poser mille fois la question : Mais qu'est-ce que j'ai bien pu vouloir faire là? Si comme moi il y a quelques jours, tu ne peux en plus pas débugger le mécanisme (en raison d'autres erreurs), alors t'es coincé.
Perso, je pense essayer d'en rajouter un peu.
A ce propos, dans ToStringConverter.hpp il semble qu'il y ait un language de description dans les commentaires. Je ne le connais pas. Serait-il possible de connaître l'outil que sait lire ça (je suppose que c'est celui qui a été utilisé pour générer le site CppReference).

Encore merci pour votre aide à tous!
Surtout à toi Kopala01

à bientôt,
Marc

[koala01]

J'espère que j'interprète bien, mais je ne suis pas vraiment d'accord : J'aurais bien pris quelques lignes d'explication dans mon code pour déverminer plus facilement les fonctions d'E/S de mon programme, et quelques autres que je vais avoir à reprendre. Tant que tu es plongé dans ton trip, tout est toujours clair. Mais laisse reposer quelques mois, et tu te retrouves à te poser mille fois la question : Mais qu'est-ce que j'ai bien pu vouloir faire là? Si comme moi il y a quelques jours, tu ne peux en plus pas débugger le mécanisme (en raison d'autres erreurs), alors t'es coincé.

Crois bien que je comprend ton point de vue, mais je peux t'assurer que, d'une certaine manière, les commentaires qui ne font pas partie des deux catégories que j'ai citées (cartouches et commentaires à visées didactiques) posent bien plus de problèmes qu'ils n'en résolvent.

Car les commentaires ne sont purement et simplement pas analysés par le compilateurs, Si bien que nous pouvons y mettre ce que nous voulons (y compris les conneries les plus ineptes), nous ne serons jamais contredit.

Or, dans le code, la seule chose qui compte réellement, la seule chose qui soit prise en compte par le compilateur, c'est le code, et rien que le code. Si on rajoute des commentaires, nous offrons à "l'un des destinataires du code" (le type qui lira le code) une "autre source d'informations", qui n'est absolument pas prise en compte par l'autre destinataire du code (le compilateur).

Mais cerveau humain est bien fait : en présence de deux sources d'informations distinctes (le code et les commentaires), il va "naturellement" privilégier la source qui lui demandera le moins de travail pour être comprise. C'est à dire qu'il privilégiera systématiquement ... les commentaires.

Le gros problème, c'est que le code, c'est quelque chose de "vivant"! Tant que l'on n'a pas décidé de mettre un "point final" au projet, le code aura de bonnes raisons de changer et / ou d'évoluer.

Mais je parle bien du code quand je dis que cela évolue !!! Pour ce qui est des commentaires:

• ou bien on oublie de les mettre à jour
• ou bien on n'ose pas trop y toucher (même si on en est l'auteur original)
• on a naturellement tendance à les lire, et à ignorer purement et simplement le code qu'ils expliquent.

Et le risque est alors de se retrouver avec des commentaires qui n'ont absolument rien à voir avec le code qu'ils sont sensés expliquer.
Nous sommes donc face à deux sources d'informations totalement désynchronisée, et dont le malheur veut que notre attention sera attirée (et captée) en priorité par ... celle qui ne correspond (peut-être) plus à la "réalité du moment" (au code tel qu'il sera exécuté réellement).

Au final, on en arrive à croire que "quelque chose" (qui a été expliqué par les commentaires) sera exécuté, alors que c'est ... autre chose (le code) qui est effectivement exécuté. Et on s'étonne de ne plus comprendre ce qui se passe!!!!

Perso, je pense essayer d'en rajouter un peu.

Oui, quelque commentaires sont parfois utiles : ce sont les cartouches, car il donnent une explication sur la manière dont tu remplis un besoin donné. Je m'explique:

Que tu décide de créer une fonction -- qu'il s'agisse de fonctions libres ou de fonctions membres ("méthode") de classe -- ou un type de donnée (qu'il s''agisse d'un alias de type, d'une classe, d'une structure, d'une union ou d'une énumération), tu le fais parce que tu as identifié un besoin que tu veux remplir.

A partir du moment où un besoin est désigné, il restera nécessaire de le remplir "jusqu'à la fin des temps", vu que le fait de rencontrer ce besoin est l'un des buts de ton projet.

S'il s'agit d'un type de donnée, n'aie pas peur de dire à quel usage il sera dédié, d'exprimer ce qu'il permet de représenter, par exemple :

Code :

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
/* représente la durée (jour, mois, année, heure, minutes secondes)
 * pendant laquelle une action ou un événement donné sera exécuté
 */
class Duration{
    /* ... 
     * Pour chaque fonction publique, une petite explication de
     * ce à quoi elle sert, des paramètres requis et de la valeur
     * renvoyée sera intéressante
     */
};
/* permet de savoir si une année est bissextile
 * 
 * une année est bissextile si sa valeur est divisible par 4 ,
 * sans être divisible par 100 ou en étant divisible par 400
 *
 * paramètre : année l'année qui doit être testée
 *
 * Renvoie "vrai" si l'année indiquée est bissextile, "faux"
 * dans le cas contraire
 */
bool estBissextile(int annee){
    /* ...*/
}

De tels commentaire resteront vrais en permanence, quel que puisse être le contenu de ma classe Duration ou de ma fonction estBissextile.

Pourquo Simplement parce que, à partir du moment où j'ai identifié le fait que j'avais besoin d'une donnée permettant de représenter les durées ou d'une fonction me permettant de savoir si l'année est bissextile ou non, je peux être sur que je vais commencer à ... utiliser cette donnée ou cette fonction.

Et je peux être sur que, dans dix ou dans vingt ans, j'aurai toujours besoin de pouvoir représenter une durée ou d'être en mesure d'évaluer si une année est bissextile.

Je me fous pas mal de savoir comment ces éléments sont implémentés (quoi que je devrais sans doute indiquer une interface qui permettrait d'obtenir les services de bases dont j'estime avoir besoin pour traiter les durées)!! je sais que, vu que j'ai eu "un jour" besoin de cette donnée et de cette fonction, j'en aurai toujours besoin .

Mais je n'ai pas créé cette classe ou cette fonction pour moi!!! je l'ai créé pour celui qui viendra "après moi", pour celui qui... aura besoin de l'utiliser, et qui devra donc savoir... comment l'utiliser correctement.

Bon, d'accord! Il se peut tout à fait que celui qui devra l'utiliser ne soit personne d'autre que moi, dans deux jours, dans un mois ou dans dix ans. Bref, dans un délais largement suffisant que pour m'avoir permis d'oublier tous les "détails sordides" de la logique que j'ai mise en place pour rendre les services attendus

Mais si je dois utiliser ce type de donnée ou cette fonction "plus tard", je m'en foutrai pas mal de ces détails sordides : je partirai du principe que j'ai fait du bon travail lorsque j'ai défini cette classe et cette fonction, et qu'elles font exactement ce pour quoi elles ont été créées à la base.

Les seules choses que j'aurai réellement besoin de savoir, c'est : comment est-ce que je dois les utiliser quels paramètres dois-je fournir dans quel ordre qu'est ce que j'obtiens en retour

Tous les autres commentaires, du genre de

Code :

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

1
2
3
4
5
6
7
8
9
10
11
12
13
bool estBissextile(int annee){
    /* vérifie si l'année est un multiple de 4 */
    if(annee % 4 == 0){
        /* vérifie si l'année est un multiple de 100 */
        if(annee % 100 == 0){
             /* ne renvoie vrai que si l'année est un multiple de 400 */
             return annee % 400 == 0;
        }
        return true;
    }
    /* si l'année n'est pas multiple de 4, elle n'est pas bissextile */
    return false;
}

ne feront qu'une seule et unique chose : paraphraser le code.

Car, soyons bien clair : ce que j'ai indiqué dans mes commentaires correspond -- pour l'instant -- exactement à ce que le code fait.

Sauf que, dans quelques mois, je vais trouver une autre logique pour faire la vérification, qui prendra trois fois moins longtemps à s'exécuter!!!

Mes commentaire ne serviront donc plus à rien et, pire encore! ils exprimeront peut être une logique qui n'a absolument rien à voir avec le code !!!

Ce genre de commentaire n'a rien à faire dans un code "de production". Au mieux, je pourrai les écrire si je veux présenter mon code à des étudiants débutants pour qu'ils comprennent la logique mise en oeuvre. Mais, même si ce n'est qu'un stagiaire dans sa première semaine de stage, je suis malgré tout en droit d'espérer que mon stagiaire connaît un minimum le C++ quand il vient travailler sur mon projet!!!

Je suis quand même en droit de partir du principe que toute personne posant les yeux sur mon code en saura suffisamment sur le langage que j'utilise pour savoir ce que représente la formule x % y == 0. Pourquoi devrais-je me faire ch...er à l'exprimer autrement

Par contre, j'ai une espèce d'obligation morale qui consiste effectivement à rendre mon code "aussi compréhensible que possible". Car j'aurai très bien pu écrire un code proche de

Code :

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

1
2
3
4
5
6
7
8
9
10
11
12
13
/* oui, ce code fonctonne !!! */
#include <iostream>
#include <ios>
#define _ bool
#define __ int
_ ___(__ _____){ return _____ % 4 == 0 ? _____ % 100 == 0? _____% 400== 0 :true :false; }
 
int main(){
    std::cout<<"1000 est bissextile ? "<<std::boolalpha<<___(1000)<<"\n"
            <<"2000 est bissextile ? "<<std::boolalpha<<___(2000)<<"\n"
            <<"2018 est bissextile ? "<<std::boolalpha<<___(2018)<<"\n"
            <<"2020 est bissextile ? "<<std::boolalpha<<___(2020)<<"\n";
}

Mais tu avouera que, bien que le code fonctionne, il est très loin d'être particulièrment compréhensible

Les quatre armes dont je dispose sont :

1. une mise en forme stricte : une instruction par ligne, ni plus ni moins
2. une indentation stricte : chaque bloc d'instruction est "décalé" par rapport au bloc d'instruction qui le contient
3. une politique de nommage qui permettra au lecteur de comprendre l'utilité de quelque chose grâce au nom qui lui a été donné
4. une politique de "casse" des noms choisi suivie scrupuleusement

Je n'ai besoin de rien d'autre pour me faire comprendre! Et surement pas de commentaires

A ce propos, dans ToStringConverter.hpp il semble qu'il y ait un language de description dans les commentaires.

Bien vu!!!

Je ne le connais pas. Serait-il possible de connaître l'outil que sait lire ça

Il s'agit de doxygen, un outil qui permet d'extraire la documentation à partir du code sources

(je suppose que c'est celui qui a été utilisé pour générer le site CppReference).

Non, sauf erreur, cppReferences est écrit en markdown
à bientôt,
Marc[/QUOTE]

[Teaniel]

Re

Il semble que nous pensions à peu près pareil. Ce que je voulais dire était bien 'une petite explication à l'entête de la fonction, éventuellement un mot à l'intérieur pour expliquer, non le comment, mais surtout le pourquoi de certaines constructions ou mécanismes un peu trop complexes, permettant d'en accélérer la compréhension'. Il n'est absolument pas dans mon ambition de commenter un getter... Inutile et insultant pour le lecteur...
Sauf que toi tu dis 'ne pas commenter' et moi l'inverse, et ce que nous faisons est au milieu... J'ai fait deux erreurs, pendant la reprise, qui ont amené des plantages parce que je n'avais pas compris la mécanique mise en place dans un appel de fonction (je devais transmettre une référence à un pointeur, ce que je n'ai pas vu et remplacé par le pointeur déréférencé (aussi un pointeur), enfin un truc pas bien quoi. Là, un petit commentaire m'aurait économisé quelques passes de débugger pour comprendre.
Merci pour tes explications.

J'ai bien compris la nécessité du caractère immuable des commentaires.
Je vais voir un peu du côté de Doxygen, la syntaxe a l'air assez intuitive (si les commentaires doivent être immuables alors il est bon que ceux qui restent utiles soient formatés de telle sorte qu'un outil de documentation puisse les extraire).

Je crois que la chose la plus importante que j'ai (re)comprise pendant ce post est que C++ est un langage, c'est à dire un ensemble d'outils (class = outil, template = outil, //, etc...), qui servent à l'humain à expliquer à une machine ce qu'il veut qu'elle fasse, et donc à ce titre, il est vital que l'assemblage utilisé de ces outils soit compréhensible par les deux parties.
Tout extrémisme dans l'usage (ou pas) de ces outils se terminera par une baisse de l'efficacité du résultat.

Encore merci à toi

A bientôt
Marc

[bacelar]

J'approuve complètement @Koala01, les commentaires inutiles, c'est caca.
Et les commentaires sont dans la très grande majorité des cas totalement inutiles.

Si vous avez besoin de commentaire pour faire comprendre comment se servir d'une API et que l'API permet de facilement mal l'utiliser, c'est que l'API a un problème.

Pour votre exemple, la signature de l'API, et particulièrement, le typage des paramètres aurait dû interdire cette "confusion" (mauvais usage).