Discussion :

[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 :

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

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 :

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

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 ?

[zekey]

Ce n'est pas réelement une réponse à ta question
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/

[Franck.H]

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

Code :

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

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

[Emmanuel Delahaye]

Bonjour

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

1) Premier format

Code :

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

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 :

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

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 :

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

1
2
3
4
 
/* ---------------------------------------------------------------------
   <comments>
   --------------------------------------------------------------------- */

En production :

Code :

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

1
2
3
4
5
6
7
8
9
10
 
/* ---------------------------------------------------------------------
   <function name> ()
   ---------------------------------------------------------------------
   <description>
   ---------------------------------------------------------------------
   I: <input parameters>
   I: <input parameters>
   O: <output values>
   --------------------------------------------------------------------- */

[Smortex]

Bonjour

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

Code :

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

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...