GEF320 Lab 2

Documentation et critique d’un programme

Objectifs

Les objectifs de ce laboratoire sont

  • de vous donner de la pratique dans la documentation des systèmes avec les diagrammes UML de classe et de séquence;
  • de vous initier à la documentation javadoc; et
  • de vous donner une opportunité de considérer une meilleure façon de structurer un petit programme comme un système des paquets, classes, attributs et méthodes.

Remise et date d’échéance

Vous devez remettre votre rapport de laboratoire et le code source par courriel avant le début du prochain laboratoire. Veuillez remettre:

  • vos deux fichiers de modèle en VP-UML;
  • un fichier .zip contenant votre code source avec commentaires, exporté selon les instructions dans le guide de survie d’Eclipse; et
  • un rapport de laboratoire concis, dans le format du laboratoire, comme fichier PDF, qui contient:
    • une brève discussion;
    • une copie de tous les diagrammes créés, exportées vos diagrammes en suivant la méthode expliquée dans le laboratoire 0; et
    • vos réponses aux questions.

La discussion doit être sur ce que vous avez appris, les découvertes que vous avez faites, ce qui a été difficile dans le laboratoire, mais pas une liste des étapes suivies ou des phrases vides sur l’importance de ce laboratoire. Soyez concis! Un paragraphe de bonne discussion vaut mieux que 10 pages de remplissage.

Introduction

On peut utiliser le langage UML comme un langage de documentation: c’est-à-dire pour documenter le design d’un système qui existe déjà. Un bon choix des diagrammes UML peut faciliter la compréhension de la structure et du comportement d’un système. Nous utiliserons UML comme langage de documentation dans ce laboratoire; la semaine prochaine, nous l’utiliserons comme langage de conception.

Le javadoc est un système pour créer de la documentation pour les programmes qui est navigable avec un navigateur web. Si vous avez utilisé le documentation de l’API de Java 8, vous avez vu du javadoc. Dans ce laboratoire vous apprendrez comment écrire et générer votre propre javadoc.

La documentation d’un système avec le langage UML peut nous aider à comprendre les avantages et inconvénient de sa conception. Dans ce laboratoire nous vous donnons deux designs d’un système et vous demandons d’en comparer divers aspects.

Préparation

Télécharger le fichier labo2bouncy-a.zip. Créer un projet Eclipse et importer le fichier. Exécuter la classe BouncyApp afin de vérifier que l’importation a fonctionné. Les instructions détaillées pour importer un fichier sont dans l’énoncé du laboratoire 1.

Refaire la même chose avec le fichier labo2bouncy-b.zip dans un autre projet Eclipse.

Les deux versions du système Bouncy ont les définitions identiques des classes Ball et Vector2D et ils ont exactement le même comportement. Les boules colorées rebondissent et vous pouvez les détruire en cliquant dessus. Si vous détruisez toutes les balles, le fond de l’écran devient gris foncé. Rien de plus.

Partie 1: Diagrammes de classe

Créer un diagramme de classes pour chaque version du système Bouncy. Parce qu’il y a des classes dans les deux systèmes avec exactement les mêmes noms (ex.: bouncy.Ball), vous aurez besoin d’un projet VP-UML séparé pour chaque version.

Vous pouvez créer les diagrammes de classes manuellement à l’aide des fonctionnalités de dessin VP-UML, ou vous pouvez utiliser la fonction « Instant Reverse » du VP-UML. N’utilisez pas la fonction « Java Round-trip ».

Si vous utilisez « Instant Reverse », vous devrez quand même comparer vos diagrammes à votre code et ajouter les éléments manquants et tout arranger de façon intelligentes. La fonction « Instant Reverse » ne trouvera pas tous les détails pertinents dans votre code. La fonction omet certaines entités et relations exigées ci-dessous.

Arranger vos diagrammes pour faciliter la compréhension des systèmes documentés.

Vos diagrammes doivent montrer:

  • toutes les classes des paquets bouncy et vector2d avec:
    • les détails de tous les attributs et méthodes non statiques (vous pouvez montrer les membres statiques, mais ce n’est pas nécessaire); et
    • le paquet auquel chaque classe appartient.
  • toutes les relations entre les classes de bouncy et vector2d, y compris les dépendances, avec tous les détails de chaque relation;
  • toutes les relations de généralisation (héritage) et réalisation (implémentation de l’interface) entre les classes de bouncy et de vector2d et les classes dans les bibliothèques standard de Java. Pour les classes et les interfaces de la bibliothèque standard de Java, vous devez montrer les paquets auxquels ils appartiennent, mais il n’est pas nécessaire de montrer les attributs et les méthodes.
  • Pour la version « b » de BouncyApp, vous devez également montrer la relation entre l’interface java.util.Observer et la classe java.util.Observable.

Partie 2: Diagramme de séquence

Créer un diagramme de séquence complet montrant tous les appels de méthode et de créations d’objets qui résultent de l’appel de la méthode movingAwayFrom(Ball other) dans la classe Ball. Si un appel de méthode provoque l’invocation d’autres méthodes, vous devez présenter la chaîne d’invocation entière.

N’utilisez pas la fonction « Instant Reverse » pour dessiner ce diagramme. Cela ne fonctionnera pas et vous n’apprendrez rien. Dessinez le diagramme manuellement à l’aide de VP-UML. Il est utile de faire une version initiale sur papier avant d’essayer avec l’outil.

Partie 3: Le javadoc

Complétez les commentaires javadoc pour la classe BoucyApp dans la version « a » du système Bouncy, et les classes BoucyApp, BounceSimulator et BouncyView dans la version « b ». Vous pouvez faire vos commentaires en français ou en anglais, selon votre préférence. Des commentaires ont été fournis pour les classes Ball et Vector2D. Vous devriez les utiliser comme des exemples de ce qui est attendu. L’article Wikipédia au sujet de javadoc fournit une explication concise du système javadoc. La documentation officielle d’Oracle, How to Write Doc Comments for the Javadoc Tool, fourni plus de détails si vous en avez besoin.

Assurez-vous d’ajouter vos noms au commentaire @author dans chaque classe.

Le javadoc est destiné à être lu dans un navigateur web après avoir été généré. Générez le javadoc pour votre projet (voir le menu « Project » dans Eclipse), y compris tous les membres dont la visibilité est privée ou plus (c-à-d tous les membres).

Regardez les messages dans la console Eclipse pour vérifier s’il y a des erreurs et pour les corriger. Regardez votre javadoc dans un navigateur web à partir du fichier index.html. S’il vous semble que la documentation n’est pas claire, qu’il manque quelque chose ou qu’elle n’est pas bien exprimée, corrigez-la. Répétez le processus jusqu’à ce que vous soyez convaincu que votre javadoc documente bien le système.

Partie 4: Questions

  1. La classe Vector2D est dans un paquet séparé du reste du système. Est-ce approprié? Pourquoi ou pourquoi pas?
  2. Il y a deux méthodes nommées plus dans la classe Vector2D. Le nom technique pour cela est le surchargement de méthode (en anglais, « method overloading »).
    1. Pourquoi la méthode plus est-elle surchargée?
    2. Lorsque plus est invoqué dans du code client, comment le système décide-t’il laquelle des deux versions exécuter?
  3. Les attributs x et y de la classe Vector2D ont un niveau de visibilité publique. Une autre approche serait de les rendre privés et de fournir les méthodes d’accès setX, getX, setY et getY. Discutez des avantages et inconvénients de ces deux approches. Dans votre discussion, examinez comment la classe Vector2D est utilisée par la classe Ball en supposant que cet usage est typique.
  4. Comparez la méthode makeBalls dans la classe BouncyApp de la version « a » avec la méthode makeBalls dans la classe BounceSimulator de la version « b ».
    1. Est-ce qu’il vaut vraiment la peine de définir les méthodes randomSize, randomVelocityComponent, randomPositionComponent et hueFromDiameter de la version « b » si l’on considère la complexité qu’ils ajoutent à la classe?
    2. Pourquoi ou pourquoi pas?
  5. Comparez la visibilité des deux méthodes makeBalls de la question 4. Quelle est la visibilité la plus appropriée? Un autre choix de niveau de visibilité serait-il préférable? Justifiez votre réponse.
  6. Comparez la structure des détecteurs d’événement (« event listeners ») dans la classe BouncyApp de la version « a » avec la structure des détecteur d’événement dans les classes BouncyView et BounceSimulator de la version « b ». (Autrement dit, quels objets sont à l’écoute pour quels événements?) Vous pouvez trouver les emplacement où les détecteurs s’attachent en cherchant les invocations de addActionListener et addMouseListener.
  7. La classe BouncyApp de la version « a » implémente l’interface java.awt.event.MouseListener. La classe intérieure BallKiller de la classe BounceView hérite de la classe java.awt.event.MouseAdapter.
    1. Si la classe BallKiller est modifiée pour implémenter l’interface MouseListener plutôt que d’hériter de la classe MouseAdapter, que devriez-vous changer dans sa structure interne?
    2. Dans vos propres mots, expliquez brièvement le but de la classe MouseAdapter.
    3. La version « a » de la classe BouncyApp ne peut pas hériter la classe MouseAdapter. Pourquoi pas?
  8. Comparer la structure globale des versions « a » et « b » du système Bouncy. Selon vous, quel système est le meilleur du point de vue de chacun des critères suivants? Justifiez vos réponses pour chaque critère en vous référant aux principes de conception logiciel discutés en classe. Soyez précis en identifiant quels aspects des systèmes vous amènent à donner ces réponses.
    1. la simplicité globale;
    2. la facilité de compréhension;
    3. la facilité de modification ou extension du système;
    4. la facilité de réutilisation des éléments du système dans d’autres contextes.
Scroll to Top