Secteur Tertiaire Informatique Filière étude - développement.

Transcription

1 Accueil Secteur Tertiaire Informatique Filière étude - développement. Activité Développer des composants d interface Etape Programmer des formulaires et des états Séance Rédiger la doc. Technique du composant Comment rédiger une documentation technique Apprentissage Période en entreprise Evaluation CODE BARRE

2 I PREAMBULE Tout bon programmeur se doit de rendre son code lisible et facile à maintenir par l'adjonction de commentaires et par la rédaction d'une documentation technique (appelée aussi documentation de conception détaillée). Ce document, réalisé à partir du dossier de conception, vise à donner une description technique de chaque composant du programme. Il constituera une référence pour la maintenance ou pour l'évolution ultérieure de l'application. II CONTENU DU DOCUMENT Il n'existe pas de normes pour la rédaction d'une documentation technique : Il vous a été proposé une maquette lors d'une séance précédente dans laquelle vous avez intégré le contexte de l application, et pour le composant développé, les fonctionnalités, les tables utilisées, et la conception de l IHM. Nous vous proposons d intégrer à ce dossier les informations suivantes: 1. Les contrôles à effectuer sur l IHM Les contrôles de premier niveau (contrôles de type, saisie obligatoire ) Les contrôles de saisie induits par l application 2. Les traitements à effectuer sur l IHM, en mentionnant les évènements sur lesquels ils sont codés. 3. La structure des fichiers Décrivez la structure de vos fichiers de données, si vous en avez Exemple : FICHIER <nom du fichier> Description <description du fichier> Type fichier séquentiel formaté/non formaté texte/binaire/objet Structure Pour un fichier classique : nom : chaîne de caractères prénom: chaîne de caractères age : entier Pour un fichier objet sérialisé : indiquez simplement la classe de l'objet Donnez un jeu d'essai pour chacun de vos fichiers de données: Exemple: Dupont Jean 22 Durand Jeanne 33 2

3 4. Les composants du programme Donnez pour chaque classe de l application, son descriptif, la liste de ses attributs et méthodes. Exemple de description de classe: CLASSE Package Description Auteurs Date et version Classe mère Attributs Constructeur Destructeur Méthodes <nom de la classe> <nom du package contenant la classe> <description de la classe> <Nom des auteurs> <Version et date de dernière modification> <nom de la super-classe dont hérite la classe) xxxx, entier, xxxx, objet Rôle du constructeur s'il existe Rôle du destructeur s'il existe Liste des méthodes de la classe (elles seront décrites plus loin) Pour chaque méthode, fonction et/ou procédure, donnez son nom et sa description, ses paramètres d'entrée et de sortie, les valeurs de retour, Pour les classes d accès aux données, précisez comment on accède aux données (requête, procédure stockée). Dans le cas de procédure stockée, précisez son nom et ses paramètres. Exemple de description de fonction ou méthode: FONCTION/METHODE <nom> Description <description> Auteur Nom des auteurs Date et version Version et date de dernière modification Paramètres d entrée xxxx, entier, xxxx, objet X Paramètres de sortie xxxx, entier, xxxx, objet X Fichiers accédés <nom du fichier> (lecture/écriture) Données manipulées Table XXXX (lecture/écriture) Accès aux données Requête / Procédure stockée (Nom et paramètres) Retour(si fonction) xxxx, entier Si le code du composant est complexe, n'hésitez pas à donner les algorithmes des parties sensibles 5. Les variables globales 3

4 III OUTILS Il existe des générateurs de documentation. Ce sont des outils de programmation qui génèrent de la documentation destinée aux programmeurs (il s'agit alors d'une documentation d'api) ou aux utilisateurs finaux (il s'agit alors d'un guide d'utilisateur) ou encore les deux. Pour gérer ces documentations, le générateur se base sur des codes sources commentés d'une certaine façon et dans certains cas également sur des fichiers binaires. Le plus connu pour java est javadoc, mais il en existe d'autres comme Doxygen qui est multi-langages. 4

5 Etablissement référent Centre Paul et Liliane GUINOT Equipe de conception V. BRUGNON Remerciements E. CATTANEO Reproduction interdite Article L du code de la propriété intellectuelle. «toute représentation ou reproduction intégrale ou partielle faite sans le consentement de l auteur ou de ses ayants droits ou ayants cause est illicite. Il en est de même pour la traduction, l adaptation ou la reproduction par un art ou un procédé quelconques.» Date de mise à jour 31/04/2008 afpa 2008 a f p a / D i r ec t i o n d e l Ing é n i e r i e1 3 p la c e d u Gé n é r a l e d e G a u ll e / M o n t r e u il C e d e x a s s o c i a t i o n n a t i o n a l e p o u r l a f o r m a t i o n p r o f e s s i o n n e l l e d e s a d u l t e s M i n i s t è r e d e s A f f a i r e s s o c i a l e s d u T r a v a i l e t d e l a S o l i d a r i t é