format de commentaires pour les entetes de fonctions

Bonjour

je me demande quel est le format el plu sefficace pour decrire ce que fait une fonction

1) Premier format

Code:

---

1 2 3 4 5 6 7 8 9

// teste si la liset est vide int // 1 : liste est vide // 0 : liste non vide LST_isEmpty( const LST_t* // IN // liste verifier el contenu );

---

ou bien
2) deuxieme format

Code:

---

1 2 3 4 5 6 7 8 9 10

// teste si la liset est vide // // Parametres // const LST_t* : IN : liset a tester // // return // 1 : liste est vide // 0 : liste non vide int LST_isEmpty( const LST_t*);

---

Remarque le deuxieme format presente une redondance pour la liset des parametres ( il peut arriver d'ajouter un parametre ou suprimer sans mettre a jour le commentaire)

Quel vortre commentaire ?

Ce n'est pas réelement une réponse à ta question :lol:
Cependant il existe pour C des outils de génération de documentation basés sur les commentaires. Donc tu serais bien inspiré de prendre leurs format de doc.
Un excellent outil est doxygen: http://www.stack.nl/~dimitri/doxygen/

Moi personnellement j'utilise le même type de commentaire qu'Emmanuel et qui me conviens parfaitement et est très agreable:

Code:

---

1 2 3 4 5 6 7 8 9 10 11

/* --------------------------------------------------------------------------   Nom fonction   --------------------------------------------------------------------------   Role :   --------------------------------------------------------------------------   E : Ici un parametre ...   E : Ici un 2° parametre ..   suivant le nom bre parametre de la fonction   S : Retour de la fonction   -------------------------------------------------------------------------- */

---

Je te conseil d'ailleurs de lire son site: http://emmanuel-delahaye.developpez....ganiser_source

Citation:

---

Envoyé par Mokhtar BEN MESSAOUD

Bonjour

je me demande quel est le format el plu sefficace pour decrire ce que fait une fonction

1) Premier format

Code:

---

1 2 3 4 5 6 7 8 9

// teste si la liset est vide int // 1 : liste est vide // 0 : liste non vide LST_isEmpty( const LST_t* // IN // liste verifier el contenu );

---

ou bien
2) deuxieme format

Code:

---

1 2 3 4 5 6 7 8 9 10

// teste si la liset est vide // // Parametres // const LST_t* : IN : liset a tester // // return // 1 : liste est vide // 0 : liste non vide int LST_isEmpty( const LST_t*);

---

Remarque le deuxieme format presente une redondance pour la liset des parametres ( il peut arriver d'ajouter un parametre ou suprimer sans mettre a jour le commentaire)

Quel vortre commentaire ?

---

Moi, je fais comme ça :

A l'arrache :

Code:

---

1 2 3 4

/* ---------------------------------------------------------------------   <comments>   --------------------------------------------------------------------- */

---

En production :

Code:

---

1 2 3 4 5 6 7 8 9 10

/* ---------------------------------------------------------------------   <function name> ()   ---------------------------------------------------------------------   <description>   ---------------------------------------------------------------------   I: <input parameters>   I: <input parameters>   O: <output values>   --------------------------------------------------------------------- */

---

Bonjour

Chacun y va de sa petite recette... Voici la mienne :

Code:

---

1 2 3 4 5 6 7 8

/* tws_lister_ls function:  * Read the contents of a directory (path), build an array of  * the found files (ls), then return its length (cnt).  */ int tws_lister_ls(char * path, DirectoryEntry ** ls) { int cnt = 0 ; [...] } /* tws_lister_ls */

---

Mais bon, l'essentiel n'est pas la forme mais le fond... Temps que l'on comprends ce qui est fait comme traitement et comment ca s'utilise en lisant juste le commentaire, c'est bon...