[C] LC II (le retour) : documentation

Date de première publication : 2013/12/10

Dans ce TP, nous allons nous intéresser à la manipulation d'une liste chaînée, la lecture d'un fichier texte et l'analyse d'un code : un guide de style prend alors tout son intérêt.

Première partie

Squelette du programme

Écrire un programme qui lit des chaînes de caractères au clavier, et les insère en fin de liste, puis lorsque la saisie est terminée on affiche le résultat.

Pour tester, n'oubliez pas que l'on peut rediriger un fichier d'entrée vers notre programme : cela simule la saisie clavier

$ prog < fichier.txt
 

On peut prendre par exemple un fichier comme celui-ci :

Guillaume de Poitiers
Rodrigo Diaz
Hugues de Payens
William Marshal
Jeanne d'Arc
Godefroid de Bouillon
Alain Quilliot :-)

La liste chaînée sera définie par la connaissance de deux pointeurs : un sur la tête, l'autre sur la fin de la liste. La cellule contient l'information texte lue.

typedef struct cellule 
{
  char             ligne[255];
  struct cellule * suiv;
} cellule_t;

typedef struct liste 
{
  cellule_t * tete;
  cellule_t * fin;
} liste_t;

Il faudra bien penser à définir la liste quand elle est vide, quand elle a un élément et quand elle en a plusieurs. Il faudra doter cette liste d'une fonction insertion en tête et d'ajout en fin de liste.

La fonction fgets() permet de ne saisir que des chaînes pas trop longues.

Pour gérer la fin de la saisie, il y a plusieurs possibilités :

• un nombre donné de ligne(s) --> TroMoche
• un fin de ligne avec un schéma connu, comme ###fin### sur une ligne par exemple --> MoinsMoche
• Utiliser le caractère de fin EOF, que l'on obtient avec CTRL+D et la valeur de retour de fgets() --> Bôhhh. Petit bémol : il faudra taper deux fois CTRL+D avec un environnement UNIX

Première amélioration

Modifier le programme précédant pour lire les chaînes de caractères dans un fichier texte donné en paramètre plutôt qu'au clavier.

int main(int argc, char ** argv  );
int main(int argc, char  * argv[]);

On pourra envisager que si l'exécutable est lancé sans paramètre, vous utilisez la version précédente. Dans le cas contraire, il faudra lire et afficher le fichier donné en paramètre.

Tester si votre programme exécutable lit bien le fichier source (texte) de votre programme.

Deuxième amélioration

Il faut modifier la structure de données pour ne stocker que des chaînes de bonne taille.

typedef struct cellule 
{
  char           * ligne;
  struct cellule * suiv;
} cellule_t;

La saisie (lecture) temporaire se fera dans une mémoire de grande taille avant copie dans une chaîne à la bonne taille.

Et encore : valgrind, valgrind, valgrind... car il faudra bien vérifer que la liste chaînée est bien complètement rendue

Statistiques et documentation

Écrire un programme qui lit sur la ligne de commande le nom d'un fichier texte correspondant à un fichier source en langage C. Vous réutiliserez donc le code de la 1ère partie. Ce nouveau programme produit en sortie un fichier texte avec uniquement :

• les directives du préprocesseur, c'est-à-dire les lignes commençant par "#"
• les prototypes des fonctions
• et les commentaires du fichier source.

Vous vous limiterez aux commentaires des entêtes des fonctions (se référer au guide de style ISIMA pour le langage C).

Le résultat doit être aéré et présenté comme une documentation, il pourrait même servir à peu de choses près de fichier " .h " pour le code C qui a été lu.

Discuter de l’utilité d’un guide de style, proposer éventuellement une norme par rapport au guide de style distribué en cours de C pour faciliter votre travail d’analyse du fichier source.

Évitez de tester tous les cas d’erreurs et ne proposez qu’un code simple mais fonctionnel.

Ajouter en tête de ce que vous produisez un bloc de commentaire qui précise : le nom du fichier, les auteurs, la date. Ce bloc peut-être :

1. déjà présent sous forme de commentaire dans le code source (c’est le plus simple) et dans ce cas ce bloc précise le rôle du programme et non le rôle d’une fonction
2. généré à partir de la balise @author et autres qui auraient été placées dans le code source [DUT, Licences]

On rappelle l'importance de se servir d'outils comme doxygen pour la génération de documentation (c'est joli et efficace donc cela donne envie de l'utiliser)

Pour ceux qui s’ennuient : Ajouter à la fin des commentaires une statistique " brute" de "qualité du code". Pour cela on calculera simplement la proportion de commentaires par rapport au code C. Cette proportion sera donnée en nombre de lignes et en nombre de caractères. Réfléchissez à la pertinence de cette mesure !