Discussion :

[foetus]

Je n'ai rien compris à votre intervention.

Il faut utiliser 1 IDE pour cela
Utilise ton moteur de recherche préféré pour rechercher "File Header Comment" (<- moi je trouve des add-ins Visual pour le faire)
Donc oui, pour ces commentaires, ils ont tous la même forme

Voici 2 exemples :

• Add document header for files automatically in Visual Studio, lien en anglais
• Header Comment Visual Studio AddIn for C#, lien codeproject.com en anglais

[koala01]

Salut,

Ce qu'il faut savoir, c'est que les développeurs aiment bien fournir des informations "utiles" aux gens qui liront leur code, ne serait-ce que pour leur permettre de comprendre le code qu'ils ont écrit.

On peut scinder ces informations en deux grandes catégories (il y a d'autres classifications possibles, celle-ci est celle qui nous intéressera le plus ):

D'un coté, on a des informations "générales" qui sont, à de très rares points de variation (comme la date à laquelle le fichier a été créé ou le nom du fichier), toujours les mêmes de fichier en fichier. Elles peuvent contenir (sans être exhaustif)

• le nom et l'adresse à laquelle contacter l'auteur du fichier
• un rappel de la licence sous laquelle le fichier est fourni
• un rappel du projet dont le fichier fait partie
• le numéro de version du fichier
• j'en passe, et de meilleures

Et, de l'autre, nous aurons des informations plus "fonctionnelles", qui décrivent les différentes fonctionnalités fournies par le fichier que le lecteur a devant les yeux.

Ces informations sont, bien sur, spécifiques à chaque fichiers, mais elles seront, malgré tout, toujours structurées de manière sensiblement identique. Par exemple, nous pourrions décrire une classe en fournissant

• une description succincte de l'objectif poursuivi la classe
• l'énoncé du besoin qui a mené à la création de la classe
• les invariants qui composent cette classe
• les "cas d'utilisation" dans lesquels cette classe sera utile
• les différences qui existent (éventuellement) entre cette classe bien particulière et d'autres classes qui pourraient avoir sensiblement le même objectif
• j'en passe et de meilleures

De même, nous pourrions décrire une fonction (qu'il s'agisse de la fonction membre d'une classe ou d'une fonction libre) en fournissant

• une brève description de ce que fait la fonction
• une description des différents paramètres dont la fonction a besoin pour travailler
• une description de la valeur de retour qu'elle est sensée renvoyer (s'il y en a une)
• les pré conditions qui doivent être respectées pour que la fonction puisse travailler
• les post conditions que la fonction devra respecter pour que l'on puisse considérer son résultat comme "cohérent"
• les exceptions qui pourraient être lancées si le comportement ne peut pas être considéré comme "cohérent"
• j'en passe et de meilleures

D'un autre coté, il faut savoir que les développeurs sont, aussi, très souvent très fainéants et que c'est "assez ch...ant" que de devoir réécrire toujours sensiblement la même chose.

C'est la raison pour laquelle la plupart des éditeurs de texte (ou des EDI) que l'on va utiliser vont nous permettre de créer des "modèles" pour ces différentes informations (et, même, de créer des modèles pour une quantité impressionnante d'éléments qui auront tendance à revenir sans cesse) que l'on peut -- a priori -- configurer "selon notre bon vouloir", selon nos propres besoins.

Si bien que, au lieu de devoir réécrire toutes ces informations dans chaque fichier, pour chaque fonctionnalité exposée dans un fichier, nous "n'aurons qu'à" utiliser un raccourcis, une séquence bien particulière de touches pour que l'éditeur de texte ajoute automatiquement le modèle de "code" que l'on a créé à l'endroit où se trouve le curseur; de manière à ce que l'on n'ait plus qu'à modifier les différents point de variation.

Pour le reste, il faut savoir que les commentaires sont, purement et simplement, totalement ignorés en C et en C++. La forme que l'on va leur donner n'a donc de l'intérêt que pour la personne qui va les écrire et -- peut être -- pour la personne qui lira le fichier.

Il se peut donc que la personne qui écrit un fichier ait certaines "habitudes", qu'elle ait une certaine vision de la manière dont les commentaires doivent être organisés et représentés. Ce sera forcément un choix tout à fait personnel, voire, un choix imposé afin d'assurer la cohérence du code au travers d'un projet.

Ce qu'il faut savoir, c'est que l'on peut, bien sur, être d'accord (ou non) avec les choix qui auront été faits, mais qu'il ne nous appartient absolument pas de remettre ces choix en question

Ainsi, l'auteur d'un fichier pourrait très bien avoir décidé que, afin d'assurer une "certaine cohérence" au niveau des commentaires, les commentaires d'ordre général seront systématiquement présentés à l'aide des symboles // et que les commentaires présentant les fonctionnalités exposées par le fichier seront systématiquement créés à l'aide des commentaire multilignes /* ... */

Au final, cela pourrait donc donner un code qui ressemblerait à quelque chose comme

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
24
25
26
27
28
29
30
31
32
33
34
// nom_du_fichier <chemin>/nom_du_fichier
// auteur: <nom> <prenom> <adresse mail>
// date: DD/JJ/AAA
// version 1.0.0
// <breve description du fichier>
//
// Ce fichier fait partie de la bibliothèque <nom du projet>
// et est fourni sous licence <licence d'utilisation>
// reportez vous au fichier LICENSE  pour plus d'informations
 
/* <breve description de classe>
 *
 * <description du besoin>
 * 
 * <intérêt de la classe>
 *
 * ...
 */
class MaClasse{
public:
    /* <brève description de la fonction>
     * 
     * <raison de l'existence de cette fonction>
     *
     * <description du premier paramètre>
     *  <description du deuxième paramètre>
     * renvoie <telle valeur> si <condition>, <telle autre valeur> dans le cas contraire
     * <pré condition à respecter lors de l'appel>
     * <post condition à respecter après exécution>
     * <exception lancée en cas de problème>
     */
    Type maFonctionQuiFaitBooh(Type2 param1, Type3 param2);
    /* et ainsi de suite */
};

Cette manière de présenter les choses en vaut largement une autre. Et, comme le compilateur ne fera absolument pas attention à tous ces commentaires, leur organisation et leur "aspect visuel" n'aura absolument aucune incidence sur le code en lui-même

[Bktero]

On parle ici de stdio.h, un fichier qui a pu être écrit par des dizaines de personnes pendant des années.

Difficile de forcer autant de personnes à utiliser le même style de commentaires, avec des règles de codage qui ont certainement évoluées dans avec le temps.

Il est possible qu'au début de l'écriture de ce fichier, seul un type de commentaire était supporté. Quand l'autre type a été autorisé, il n'était pas question de changer les anciens commentaire juste pour aligner des styles.

Aussi, il est possible que ce fichier soit en partie généré, assemblant des morceaux de code de différentes sources.

Conclusion : ce n'est vraiment pas le genre de fichiers à prendre en exemple.....et pas uniquement sur les commentaires !

[Invité]

On parle ici de stdio.h, un fichier qui a pu être écrit par des dizaines de personnes pendant des années.

Même pas en fait. C'est UNE implémentation de stdio.h. Celle que j'utilise (glibc) n'a que des commentaires au format /* ... */.

[koala01]

Même pas en fait. C'est UNE implémentation de stdio.h. Celle que j'utilise (glibc) n'a que des commentaires au format /* ... */.

As tu un change log git, mercurial, ou autre à ta disposition pour affirmer cela

Ou, peut-être, peux tu l'affirmer parce que tu es l'auteur du fichier, et que tu es le seul à y avoir apporté des modifications

stdio.h fait partir de la bibliothèque standard du C depuis quoi? cinquante ans Du moins, peut on imaginer qu'un fichier qui fournit des entrée sortie standard pour un langage (quel qu'il soit) existe -- a priori -- depuis presque aussi longtemps que le langage en lui-même, ne crois tu pas?

Alors, tu as raison sur un point: chaque compilateur, chaque fournisseur de libC va fournir sa propre écriture du fichier stdio.h. Cela ne veut pas dire qu'il n'y a eu qu'un seul auteur, ou qu'il n'a pas évolué (ou que les règles de codage en vigueur dans l'équipe qui s'occupe d'implémenter la biliothèque n'aient pas évolué) depuis qu'il a été écrit la première fois

Edit:
Pour ma part, j'ai trouvé l'historique (git) du fichier de stdio.h pour la glibc ==>ICI<==, et j'ai rapidement compté:

Entre le premier avril 2011 et le cinq juin 2018, il n'y a pas eu moins de 35 commits sur ce fichier que l'on aurait pourtant pu croire particulièrement stable, et il y a eu au moins huit auteurs différents pour les commits.

[Invité]

As tu un change log git, mercurial, ou autre à ta disposition pour affirmer cela...

Je répondais à la remarque qui disait en gros que "le fichier stdio.h n'est pas un bon exemple de commentaires homogènes" en précisant que "stdio.h" n'a pas qu'une implémentation et que certaines implémentations ont des commentaires homogènes. Si tu ne me crois pas, tu peux vérifier par toi-même en récupérant les sources (https://www.gnu.org/software/libc/sources.html) et en faisant un find glibc-2.31/ -name stdio.h -exec grep "//" {} \;.