1- Document de conception
publicité
Aide à la rédaction d’un travail pratique idée originale : Gilles-Philippe Grégoire Stéphane Lévesque Anne Raby Adaptation: Pierre Bélisle Guide des travaux pratiques automne 1997 page 1 Table des matières 1. DOCUMENT DE CONCEPTION ..................................................................................................................................................... 3 DÉFINITION DU PROBLÈME ...................................................................................................................................................................... 3 PRÉCISIONS CONCERNANT LES SPÉCIFICATIONS ...................................................................................................................................... 3 LE DIAGRAMME HIÉRARCHIQUE .............................................................................................................................................................. 3 L’ALGORITHME GLOBAL DE HAUT NIVEAU .............................................................................................................................................. 4 L’ALGORITHME SPÉCIFIQUE .................................................................................................................................................................... 4 LA STRATÉGIE DE VÉRIFICATION(LES RÉSULTATS ATTENDUS) ................................................................................................................. 4 2. CODE SOURCE .................................................................................................................................................................................. 6 3. JEUX D'ESSAI..................................................................................................................................................................................... 7 JEUX D'ESSAI (LES RÉSULTATS OBTENUS) ............................................................................................................................................... 7 LES LIMITES DU PROGRAMME ................................................................................................................................................................. 7 4. GUIDE DE L’UTILISATEUR ............................................................................................................................................................ 7 5. DISQUETTE ........................................................................................................................................................................................ 8 6. QUALITÉ DE LA PRÉSENTATION ................................................................................................................................................ 8 ANNEXE A ............................................................................................................................................................................................... 9 LA DISQUETTE : ....................................................................................................................................................................................... 9 L’ENVELOPPE .......................................................................................................................................................................................... 9 LA PAGE COUVERTURE DU DOCUMENT .................................................................................................................................................. 10 Guide des travaux pratiques automne 1997 page 2 1. Document de conception Définition du problème À FAIRE Vous devez montrer, dans vos propres mots, que vous comprenez ce qu’il faut faire. Vous expliquez le problème, le défi à résoudre ou à surmonter. Le document doit être composé de manière à ce que n’importe quel collègue, qui n’a pas lu l’énoncé préalablement, puisse bien comprendre ce qu’il y a à faire À NE PAS FAIRE Cette partie n’est pas une copie de l’énoncé Ne doit pas faire état de la méthode de solution N’est pas une description du programme Précisions concernant les spécifications Ce sont les détails importants ; Les contraintes de l'usager ou du contexte. On retrouve les exigences relatives au problème telles : Formule de calcul Règles d’affaires, règles de traitement Conditions de validation ****On doit en combinant ces deux parties(définition du problème et précisions concernant les spécifications, retrouver toutes les parties essentielles à la résolution du problème. Tous les détails doivent y être. Le diagramme hiérarchique À FAIRE identifier chacune des étapes logiques du programme Chaque boîte représente une étape qui devrait par la suite correspondre à une procédure utiliser des verbes, énoncer une action arrêter de décomposer quand les étapes peuvent naturellement être transposées en code Il n’est pas nécessaire de le faire par ordinateur, vous pouvez le faire à la main (ÉCRITURE LISIBLE) mais faites-le complètement, c’est-à-dire les boîtes, et les lignes reliant les boîtes(seulement pour le premier travail) À NE PAS FAIRE Un arbre décisionnel, mais une structure de programme Un ordinogramme, un organigramme ou un structurogramme détaillé(condition, boucle) Un diagramme de flux, ne pas utiliser de flèches Guide des travaux pratiques automne 1997 page 3 L’algorithme global de haut niveau À FAIRE S’inspirer du diagramme hiérarchique. Donner le fonctionnement de ce qui se passe à l’intérieur du premier niveau du diagramme refléter ce que sera le programme, abstraction faite du langage de programmation, utiliser des descriptions, pas des étiquettes, À NE PAS FAIRE mentionner des appels de procédure ou des noms de procédure utiliser du code ou des symboles spécifiques au code L’algorithme Spécifique À FAIRE Prendre les parties de l'algorithme global qui nécessitent d'être plus spécifiées Si dans un algorithme spécifique, des parties méritent spécifications, on le fait ici. Cet algorithme spécifique en question, devient donc comme un algorithme global. Écrire autant d'algorithmes que nécessaires pour la bonne compréhension de la solution. Détailler les algorithmes même s'ils sont connus (ex. algorithme de tri ) À NE PAS FAIRE mentionner des appels de procédure ou des noms de procédures ou fonctions utiliser du code ou des symboles spécifiques au code oublier les algorithmes de calcul La stratégie de vérification(les résultats attendus) À FAIRE une explication de la démarche de vérification du programme on explique le cheminement des tests, pourquoi on fait tel ou tel test, c’est ce à quoi on s’attend on doit retrouver les raisons qui justifient chacun des tests on explique les cas normaux, limites, hors bornes et erronés, en mentionnant des valeurs pour chacun des tests tests, à la main, de ce que le programme devrait donner calculer les résultats que l’on devrait avoir, pour ensuite les comparer avec l’exécution, s’il y a concordance, le programme devrait être bon On doit retrouver les résultats attendus des essais fournis par le professeur ET les essais personnels, qui proviennent de la stratégie de vérification Peut-être sous forme de tableau (idéalement) Numéroter les tests et faire correspondre ces tests avec les tests sur l’exécution À NE PAS FAIRE l’exécution du programme seulement l’énoncé des tests, faut aussi retrouver les explications Guide des travaux pratiques automne 1997 page 4 Les structures de données À FAIRE expliquer les structures de données utilisées dans le programme (s’il y a lieu) on explique comment est formée la structure, ce qu’il y a dedans, comment elle est utilisée, doit être clair et donner un aperçu de ce que l’on retrouve dans le programme, pour ne pas avoir à le deviner s’il n’y en a pas, dans le programme, ne rien écrire il faut inclure, entre autres : - les types construits - les enregistrements - les tableaux - les fichiers - les matrices - etc. - ... À NE PAS FAIRE du code ADA ou autre une liste exhaustive des variables retrouvées dans le programme l’explication des différentes procédures du programme Description des entrées/sorties pour chaque future procédure ou fonction À FAIRE Décrire tout ce qui entre(provient du clavier, de fichiers etc.) et qui sort du programme principal(Écran, fichiers etc.) Décrire tout ce qui entre et qui sort des sous-programmes On y retrouve une description, un nom, un pseudo-type ENTRÉE : ce sont les futurs paramètres formels en IN ou IN OUT SORTIE : ce sont les futurs paramètres formels en OUT ou IN OUT À NE PAS FAIRE Un écran de sortie provenant de l’exécution du programme La transcription de la partie déclarative Ne pas utiliser les noms de variables spécifiques au programme Guide des travaux pratiques automne 1997 page 5 2. Code source Le code est corrigé seulement s’il est imprimé, Imprimer le code en police de caractères COURIER 10 ou 8, minimum 7 À FAIRE imprimer le code sur du papier, en utilisant le format paysage, de préférence enlever les bretelles séparer les pages de papier continu imprimer le même document qu’il y a sur la disquette mettre les constantes, puis les variables en ordre alphabétique ou dans un ordre logique ordre des déclarations constante : nom significatif et ordre alphabétique ou regroupement logique type : nom significatif et ordre alphabétique ou regroupement logique sous-type : nom significatif et ordre alphabétique ou regroupement logique packages : nom significatif et ordre alphabétique ou regroupement logique sous programmes(procédures et fonctions) variables : nom significatif et ordre alphabétique ou regroupement logique bien identifier les déclarations commentaires d’en-tête numéro du cours nom du professeur nom de l'étudiant ce que le programme fait (1 ou 2 lignes) date compilateur utilisé commentaires pour toutes les déclarations, chaque variable, constante, etc. commentaires pour chaque étape importante du code cohérence dans le code : indentation des instructions et choix des identificateurs respecter la structure de l'algorithme l'indentation est importante UNE SEULE instruction ou déclaration par ligne aérer le code par des lignes vides et des espaces (quand c’est nécessaire) utiliser des paramètres pour transmettre l'information entre sous programmes. À NE PAS FAIRE ne pas imprimer du code qui déborde de la page ne pas ordonner les constantes et variables par les types mettre des accents dans le code, ni dans les commentaires du code-source ne pas utiliser de variables globales. Guide des travaux pratiques automne 1997 page 6 3. Jeux d'essai Les résultats obtenus C’est l’exécution du programme, on doit comparer les résultats obtenus avec ceux attendus. S'il y a des différences, il faudra recommencer le cycle pour trouver l'erreur et la corriger. À FAIRE les tests, du jeu d’essais fournis par le prof et de votre jeu d’essais tel que déterminé dans la stratégie de vérification, exécutés par le programme vous devez écrire l’explication à côté du test, puisqu’il peut en avoir beaucoup l’exécution du programme en utilisant un utilitaire comme SCRIPT.COM À NE PAS FAIRE tous les tests un à la suite de l’autre sans explication, faut dire à quoi on fait référence Les limites du programme C’EST ce que le programme peut faire et ne peut pas faire les cas d’erreurs qui ne sont pas résolus les bogues du programme connus et qui ne sont pas réglés les fonctionnalités (du programme) non implantées les limites cernées par l’utilisateur et celles intrinsèques et implicites au programme CE N’EST PAS une partie de cache-cache, il n’est pas souhaitable de camoufler des problèmes ne pas mélanger les contraintes de l'usagers avec les limites. Par exemple qu'il n'y ait pas de note F n'est pas une limite du programme, mais une contrainte du contexte. 4. Guide de l’utilisateur LE GUIDE S’ADRESSE À L’UTILISATEUR, FAITES COMME S’IL NE SAVAIT PAS CE QUI S’EN VIENT Expliquer comment démarrer le programme Expliquer brièvement le fonctionnement et le cheminement du programme, du début à la fin, comment utiliser le programme Donner des exemples d’écrans, définir le contenu, donner un exemple d’entrée et de sortie Expliquer quoi faire en cas d’erreur de l’utilisateur Quels sont les messages qui apparaissent à l’écran? Donner des instructions claires et précises Donner les informations à saisir avec les limites des valeurs permises À NE PAS FAIRE Demander à l’utilisateur de partir ObjectAda et de compiler le code source(il utilise l’exécutable) Dire de cliquer sur telle icône sans dire comment y accéder Dire de taper TP1 dans DOS n’est pas suffisant Guide des travaux pratiques automne 1997 page 7 5. Disquette ON DOIT RETROUVER SUR LA DISQUETTE : 1. OBLIGATOIRE le programme source : xxxx.ada 2.OPTIONNEL document de conception guide de l’utilisateur jeux d’essais, s’il y a lieu une version exécutable : xxxx.exe À FAIRE : Il faut remettre seulement ce qui est demandé, rien d’autre Mettre les fichiers sur le répertoire principal de la disquette Enlever les virus de la disquette À NE PAS FAIRE : Remettre une disquette avec un ou des virus Remettre le projet complet créé par ObjectAda Mettre plus d’un code source ou une version exécutable sur la disquette 6. Qualité de la présentation Faire une page couverture avec toutes les informations pertinentes (voir exemple : annexe A) Faire une table des matières avec pagination Paginer tout le document, au complet Ne remettre qu’UN SEUL document Brocher ou relier le document ET s’assurer que la reliure ne cache pas du texte ou n’empêche pas de lire aisément le document Remettre le document et la disquette dans une enveloppe cachetée Vérifier et faire vérifier l’orthographe Remettre une seule disquette Bien identifier l’enveloppe, la disquette et le document (voir exemple : annexe A) À NE PAS FAIRE Utiliser un trombone ou tout autre attache qui tient mal Utiliser une enveloppe de format trop juste qui déchire quand on remet le document dedans écrire le document à la main Guide des travaux pratiques automne 1997 page 8 Annexe A la disquette : nom groupe cours numéro du tp code permanent compilateur utilisé l’enveloppe nom groupe cours numéro du tp nom du professeur semestre TP1 par Albert Camus Cours : INF 1110 gr. 21 Prof : Chuck Yeagers Automne 97 Remis le 12 septembre 1986 Code permanent Guide des travaux pratiques automne 1997 page 9 la page couverture du document nom groupe cours numéro du tp nom du professeur semestre date de remise etc. TP1 Calcul de moyenne Par Albert Camus Code permanent Remis à Ada Lovelace Dans le cadre du cours INF 1110 Groupe 23 Université du Québec à Montréal 14 juillet 1885 Guide des travaux pratiques automne 1997 page 10
