Guide pour la rédaction
des rapports de projets

Documents à produire.

• Document de 5 à 10 pages présentant le projet. Des annexes permettent de présenter le code et des références éventuelles.
  1. Une version papier sera déposée au lycée à la date qui vous sera indiquée en cours d'année.
  2. Une version numérique au format pdf sera fournie (déposée sur le forum à votre nom) à la même date.
  3. Le code (fichiers .py et tout fichier nécessaire à l'exécution) sera également déposé sur le forum à votre nom à la même date.
  Un rapport par personne.
• Support numérique pour l'oral : il s'agira d'un support html.
  • Ce peut être par exemple un diaporama (html) écrit à l'aide d'une application javascript dédiée (on en trouve sur le web). A vous de trouver une forme qui vous convient pour le support de votre oral.
  • Une autre idée s'intégrant bien avec un support html et permettant une présentation dynamique : utiliser un logiciel de mind-mapping.

A propos du code.

1. Le code fourni doit évidemment fonctionner.
2. L'utilisateur de votre code doit pouvoir le faire fonctionner sans consulter votre rapport : le mode d'emploi, des indications... doivent être intégrés au code de façon claire.
3. Le code doit fonctionner sous linux comme sous windows. Notamment interdiction d'utiliser des modules spécifiques à windows (par exemple le module winsound pour ceux qui aiment mettre du son). Si votre programme gère des fichiers, vous ferez en sorte que les chemins ne suivent pas une syntaxe liée à un OS : les chemins seront indiqués sous la forme "dossier/sousdossier/fichier" (avec des barres / et non des barres \). Consultez également le module os.
4. Attention à l'erreur faite de tester toujours sur le même écran. Si vous utilisez une fenêtre tkinter avec des boutons pour déclencher les actions, assurez vous que les boutons soient accessibles depuis tout écran.
   Attention en particulier aux fenêtres tkinter paramétrées avec des valeurs fixes : si vous déclarez une fenêtre de 900 px de haut et que l'utilisateur a un écran de 700 px, il risque fort de ne pas voir une partie des boutons et de ne pas pouvoir faire fonctionner votre programme. Utiliser toujours des dimensions relatives à la taille de l'écran pour les fenêtres tkinter.
5. Votre programme sera commenté en détails.
   • Il ne s'agit surtout pas de mettre en face de l'instruction

     a = 5

     un commentaire du genre "on stocke 5 dans a" ! Ce sont les rôles, les objectifs de chaque partie qu'il faut expliciter, ainsi que le rôle du contenu des variables. Si par exemple, la variable a de a = 5 compte le nombre de points d'un joueur, cela doit être compris par lecture des commentaires sur le code (mais un nom plus explicite que "a" doit par ailleurs être utilisé : pensez systématiquement à nommer vos variables avec un nom lié à leur rôle).
   • Les fonctions définies (et les classes si vous en avez utilisées) doivent présenter un docstring explicite (input, output, descriptif de l'algorithme choisi éventuel...). La forme utilisée sera la suivante :

         
         def nomFonction( paramètres ) :
     		"""
     		auteur : nom du membre du groupe auteur de cette fonction
     		entrées :  type  des entrées et rôle dans le programme
     		sorties : type des sorties et rôle dans le programme
     		Rôle : rôle spécifique de la fonction dans le programme.
     		Choix de programmation : choix de structure, d'algorithme
     		"""
     		instructions de définition de la fonction
         
         

     Les groupes utilisant des classes suivront le même type de commentaire pour leurs classes.
   • Lorsque vous avez fait des choix de structure, ils doivent être explicités (par exemple, dans une grille de sudoku, choix de la structure pour stocker pour chaque cellule les candidats possibles à un moment donné : liste, listes imbriquées, tuple, string, autres...?)
   • On doit au final pouvoir lire et comprendre votre programme sans lire une seule ligne de code : lire les commentaires devraient suffire. Ces commentaires, visuellement distincts du code (utilisation de couleur), présente en particulier les algorithmes de façon synthétique. Écrire en français la même chose que ce qui est écrit en python ne sert à rien : une boucle par exemple sera résumée essentiellement par son effet.
6. Attention au code déposé au dernier moment. Chaque année, des élèves peu rigoureux oublient de déposer un dossier complet (par exemple dépôt du code sans les images utilisées, le code ne peut donc pas fonctionner). De même chaque année, des élèves font des modifications de dernière seconde et déposent du coup un code ne fonctionnant pas. DANS TOUS LES CAS, faîtes une vérification du bon fonctionnement de votre code avant de le déposer.

Partie principale du rapport.

• Les pages doivent être numérotées, ainsi que les paragraphes (l'objectif est de pouvoir référencer rapidement une partie de votre rapport afin de vous poser des questions claires avant l'oral pour vous préparer ou pendant l'oral).
  • Les caractères auront une taille de 11 ou 12 points, interligne et marge standards (autrement dit : ne pas tricher en grossissant artificiellement la taille des caractères et les marges, cela vous pénaliserait dans l 'évaluation).
  • Les images uniquement décoratives sont interdites, toute image doit avoir un rôle explicatif et la place qu'elles prennent doit être raisonnable.
• Dans la partie principale du rapport, le projet sera clairement présenté (mais sans les détails du code). On pourra trouver les thèmes suivants (d'autres sont possibles, n'hésitez pas à être créatifs dans votre présentation) :
  • Présentation du sujet avec un petit rappel "historique" si le sujet s'y prête.
  • Analyse du problème posé.
  • Algorithme de la (ou des) fonction(s) importante(s).
  • Jeux d'essais. On trouvera par exemple ici le détail des tests réalisés pour comprendre et débuguer une fonction qui vous a posé problème durant l'écriture, ainsi que les solutions trouvées. On pourra aussi ici trouver une éventuelle série de tests (avec le détail du code en annexe) exécutés pour vérifier que votre programme fonctionne sans bugs (on se pose ici, par exemple, la question de savoir comment réagit le programme si l'utilisateur se trompe en entrant une valeur)
  • développements possibles.
  • Un lien avec les notions apprises pendant l'année doit être fait.
  • Attention à ne pas commettre l'erreur souvent rencontrée dans les rapports d'écrire des pages de commentaires du point de vue de l'utilisateur du jeu développé (ou de l'application quelle qu'elle soit). Si les explications pour l'utilisateur sont longues, elles seront rejetées en annexe. C'est le point de vue du programmeur qui doit être développé dans les pages principales.
• Dans l'exposé (et en partie principale du rapport), prévoir d'expliquer tout ou partie du programme.
  • Plutôt que le code python, on présentera ici du pseudo code mettant l'accent sur l'essentiel des idées : il s'agira de montrer votre capacité à faire ressortir les principales étapes d'un algorithme en prenant du recul par rapport au détail du code.
  • Utiliser des algorigrammes (ou organigrammes) est nécessaire, cela permet au lecteur d'avoir une vue d'ensemble et vous contraindra à développer cette vue d'ensemble (il est conseillé d'écrire de tels schémas dès le début du projet, ils pourront évolués mais serviront de guide, de garde-fou, de pense-bête...). Chercher sur le web les conventions usuelles pour ces schémas. Vous pouvez par exemple consulter cette page. Un logiciel efficace et facile de prise en main pour les algorigrammes : draw.io (vous n'avez rien à installer sur votre machine, travail en ligne).
  • Un pseudo-code ou un algorigramme permet de présenter du code avec plus ou moins de hauteur. Certaines parties de la présentation pourront être très proches du code si vous pensez qu'un point de détail est intéressant à expliciter. Mais on peut aussi avoir une présentation où toute une série d'instructions est résumée par son effet, cela permet en effet d'avoir une vue d'ensemble en oubliant provisoirement les détails. Les choix à faire ici dépendront de votre travail et ne doivent pas être négligés dans votre rapport.
  • Les algorigrammes sont souvent un bon support pour l'oral : synthétique, ils vous permettent d'avoir l'essentiel sous les yeux et donc de ne rien oublier, sans pourtant lire vos notes (lire ses notes est évidemment à éviter lors de l'oral).
• La répartition des tâches entre les deux membres du groupe lors de la réalisation du projet devra clairement ressortir dans le rapport de chacun. Une partie peut être commune aux deux membres du groupe mais chacun devra développer dans son rapport la partie sur laquelle il a travaillé.
  • Attention, pas de bla bla creux du genre "tel jour j'ai cherché et j'ai pas trouvé" comme on a pu parfois en lire sur certains tpe : vous présentez ce que vous avez trouvé, vous analysez en quoi la documentation trouvée convenait ou ne convenait pas.
  • De même si une partie importante de travail a été abandonnée, une analyse détaillée du pourquoi de cet abandon sera réalisée.
    • Ne pas aboutir à un travail fini sous prétexte d'une impasse lors du travail sera sanctionné sauf si une véritable réflexion permettant de comprendre les échecs est menée.
    • A l'opposé, si votre travail est abouti, certains développements de code ayant échoués gagneront à être présentés : le présenter en expliquant pourquoi il a échoué peut être un plus, surtout si ce code vous a demandé beaucoup de travail et ne s'est révélé inefficace que tardivement dans l'avancée de votre projet.
• Répartition des tâches et calendrier.
  • La répartition des tâches et les objectifs ne se définissent pas après coup. Ces tâches et un plan de travail doivent être réalisés le plus tôt possible et écrits explicitement, ils peuvent bien sûr évolués mais doivent rester une préoccupation constante. Ils seront donnés dans les annexes et peuvent se retrouver partiellement dans la partie principale comme support de l'exposé. Attention au contenu vide : il s'agit d'exposer des tâches de travail, des objectifs scientifiques, pas de raconter si vous étiez en panne d'inspiration lundi 18 à 14h.
  • Le calendrier de l'avancée de votre projet et la répartition des tâches gagnent souvent à être résumés sous une forme synthétique, notamment sous la forme classique d'un diagramme de Gantt.
• Si la réalisation du projet est un travail mené en commun, le rapport final est personnel : chacun est seul devant le jury le jour de l'oral et ne peut pas s'appuyer sur son camarade. A chacun de vous de veiller à avoir un contenu solide à présenter le jour j.
  Veillez également à connaître le contenu du travail de votre binôme même si les examinateurs n'exigeront pas a priori une connaissance aussi détaillée que pour votre partie. Attention, toutefois à l'équilibre : un candidat qui aurait beaucoup moins fourni de travail que son binôme devra essayer de compenser un peu en ayant une bonne connaissance de l'ensemble du projet (par exemple, un élève qui se serait contenté de travailler l'interface alors que son binôme aurait tout développé le jeu, les stratégies... Il est clair qu'il ne faut pas répartir les tâches ainsi mais il serait encore pire dans ce cas de se présenter devant le jury en n'ayant connaissance que de sa partie).

Les annexes du rapport.

On pourra trouver dans les annexes d'autres parties en plus de celles citées ci-dessous. N'hésitez pas à être inventif.

• Certaines parties citées ci-dessus en partie principale peuvent se trouver partiellement dans les annexes (dans le cas où une partie serait trop longue, trop détaillée : reportez les détails aux annexes, réservez les idées essentielles à la partie principale). A vous de trouver un équilibre adapté à votre travail.
• Dans l'annexe (donc en dehors des 5 à 10 pages constituant la partie principale du rapport) on trouvera le code de votre programme. Comme nous disposerons déjà du fichier code, il s'agit ici d'insister sur la structure de votre code : certaines fonctions pourront par exemple être présentes uniquement sous la forme de leur entête et docstring. A vous dans cette annexe de faire en sorte de trouver un équilibre afin que de ne pas imprimer tout votre code mais de faire en sorte que le lecteur comprenne au mieux l'ensemble de votre programme en lisant cette partie. Un lecteur sachant programmer devrait pouvoir facilement écrire lui-même le code manquant : pour cela, votre présentation doit être explicite, les noms des variables importantes et leurs rôles doivent apparaître...
• Les sources. Lors de votre travail de programmation, il vous faudra compléter vos connaissances par des recherches, notamment sur le web. L'annexe comportera une partie citant les sources, notamment l'adresse et ce que vous avez utilisé, appris avec cette source. Attention, à remplir cette rubrique au fur et à mesure de votre travail. Vous serez incapable de remplir une telle rubrique au dernier moment sans prise de note rigoureuse au fur et à mesure de l'avancée du travail.

Insistons

Des éléments d'évaluation importants de vos rapports (et de l'oral) :

• Le rapport présente les choix du point de vue programmeur et non la vue du point de vue utilisateur (les détails d'utilisation sont présents en annexe et dans l'interface à l'exécution du programme).
• Le rapport présente des algorigrammes permettant de synthétiser, de prendre du recul sur la structure du code.
• Votre travail personnel apparaît clairement.
• Le code est commenté (notamment docstrings correctement écrits) et découpé en fonctions rendant la lecture aisée. Les variables ont des noms explicites permettant de saisir facilement leur rôle.