diff --git a/README.md b/README.md index 9365b9a1c7ff3f61c879816cdd9c09907579592b..71a3e93c3f3b0201dd6f2a9ff817d7101eace2ae 100755 --- a/README.md +++ b/README.md @@ -1,237 +1,236 @@ -# Projet: calculator - -Auteurs: Michael Kölling and David J. Barnes -Traduction: Laurent Pierron - -Ce projet fait partie du matériel pour le livre - - **Objects First with Java - A Practical Introduction using BlueJ - Fifth edition - David J. Barnes and Michael Kölling - Pearson Education, 2012** - -Il est expliqué dans le chapitre 7. - -Une réalisation d'une calculatrice de bureau. Cet exemple renforce les concepts vus précédemment et est utilisé pour discuter le débogage et le test. -Une version avec une interface graphique est incluse dans la branche `calculator-gui`. - -- - - - -## Préparation du projet - -1. Créer un clone du projet **calculator** sur votre machine. -2. Créez une branche avec votre nom de login. -3. Synchronisez votre branche sur https://gitlab.univ-lorraine.fr. - -- - - - -## Expression du besoin - -On vous a demandé de joindre une équipe chargée de développer une calculatrice logicielle, car un des membres essentiels de l'équipe, Hacker T. Largebrain, a été promu pour diriger un autre projet. -Avant de quitter le projet, Hacker a assuré à l'équipe que vous rejoignez que la réalisation de la partie de calculatrice dont il était responsable était terminée et complètement **testée**. Il a même écrit un logiciel de test pour vérifier que c'était le cas. On vous a demandé de reprendre la classe `CalcEngine` et de vous assurer simplement qu'elle est correctement documentée avant son intégration aux classes développées par les coéquipiers. - - - -Dans l'application des bonnes pratiques de découpage des applications, le projet de calculatrice a été conçu en séparant l'interface utilisateur du moteur de calcul. La première version, que nous étudierons ici, fonctionnera avec une interface graphique (*GUI*) montrée ci-dessous. Plus tard la même calculatrice pourra être utilisée pour créer une application Web et une application pour smartphone. En préparation de cela l'application a été divisée en deux classes : - - 1. `UserInterface` : interface utilisateur graphique, - 1. `CalcEngine` : réalisation de la logique de calcul. - -Hacker était responsable de cette seconde classe. Elle ne devra pas changer quand la calculatrice aura une nouvelle interface. - -Deux autres classes sont présentes pour vous aider à tester la calculatrice : - -1. `Calculator`: programme de lancement de la calculatrice graphique -1. `CalcEngineTester` : programme de test du moteur de calcul, ce programme a été réalisé par Hacker - -## Interface et documentation de `CalcEngine` - -L'analyse du projet de calculatrice a abouti à définir les responsabilités de la classe `CalcEngine` sous la forme d'une liste de méthodes, dont voici la carte de description UML : - - - -```plantuml -@startuml -class CalcEngine { -+ clear() -+ equals() -+ getAuthor() : String -+ getDisplayValue() : int -+ getTitle() : String -+ getVersion() : String -+ minus() -+ numberPressed(int) -+ plus() -} -@enduml -``` - - -Une fois cette description UML transcripte dans le langage Java, la classe `CalcEngine` devrait avoir une `javadoc` associée, dont une partie est affichée ici : - - - -\begin{comment} - -<!-- ======== CONSTRUCTOR SUMMARY ======== --> - -<section role="region"> -<ul class="blockList"> -<li class="blockList"><a id="constructor.summary"> -<!-- --> -</a> -<h3>Constructor Summary</h3> -<table class="memberSummary"> -<caption><span>Constructors</span><span class="tabEnd"> </span></caption> -<tr> -<th class="colFirst" scope="col">Constructor</th> -<th class="colLast" scope="col">Description</th> -</tr> -<tr class="altColor"> -<th class="colConstructorName" scope="row"><code><span class="memberNameLink"><a href="#%3Cinit%3E()">CalcEngine</a></span>()</code></th> -<td class="colLast"> -<div class="block">Create a CalcEngine instance.</div> -</td> -</tr> -</table> -</li> -</ul> -</section> -<!-- ========== METHOD SUMMARY =========== --> -<section role="region"> -<ul class="blockList"> -<li class="blockList"><a id="method.summary"> -<!-- --> -</a> -<h3>Method Summary</h3> -<table class="memberSummary"> -<caption><span id="t0" class="activeTableTab"><span>All Methods</span><span class="tabEnd"> </span></span><span id="t2" class="tableTab"><span><a href="javascript:show(2);">Instance Methods</a></span><span class="tabEnd"> </span></span><span id="t4" class="tableTab"><span><a href="javascript:show(8);">Concrete Methods</a></span><span class="tabEnd"> </span></span></caption> -<tr> -<th class="colFirst" scope="col">Modifier and Type</th> -<th class="colSecond" scope="col">Method</th> -<th class="colLast" scope="col">Description</th> -</tr> -<tr id="i0" class="altColor"> -<td class="colFirst"><code>void</code></td> -<th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#clear()">clear</a></span>()</code></th> -<td class="colLast"> -<div class="block">The 'C' (clear) button was pressed.</div> -</td> -</tr> -<tr id="i1" class="rowColor"> -<td class="colFirst"><code>void</code></td> -<th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#equals()">equals</a></span>()</code></th> -<td class="colLast"> -<div class="block">The '=' button was pressed.</div> -</td> -</tr> -<tr id="i2" class="altColor"> -<td class="colFirst"><code>java.lang.String</code></td> -<th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#getAuthor()">getAuthor</a></span>()</code></th> -<td class="colLast"> </td> -</tr> -<tr id="i3" class="rowColor"> -<td class="colFirst"><code>int</code></td> -<th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#getDisplayValue()">getDisplayValue</a></span>()</code></th> -<td class="colLast"> </td> -</tr> -<tr id="i4" class="altColor"> -<td class="colFirst"><code>java.lang.String</code></td> -<th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#getTitle()">getTitle</a></span>()</code></th> -<td class="colLast"> </td> -</tr> -<tr id="i5" class="rowColor"> -<td class="colFirst"><code>java.lang.String</code></td> -<th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#getVersion()">getVersion</a></span>()</code></th> -<td class="colLast"> </td> -</tr> -<tr id="i6" class="altColor"> -<td class="colFirst"><code>void</code></td> -<th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#minus()">minus</a></span>()</code></th> -<td class="colLast"> -<div class="block">The '-' button was pressed.</div> -</td> -</tr> -<tr id="i7" class="rowColor"> -<td class="colFirst"><code>void</code></td> -<th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#numberPressed(int)">numberPressed</a></span>​(int number)</code></th> -<td class="colLast"> -<div class="block">A number button was pressed.</div> -</td> -</tr> -<tr id="i8" class="altColor"> -<td class="colFirst"><code>void</code></td> -<th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#plus()">plus</a></span>()</code></th> -<td class="colLast"> -<div class="block">The '+' button was pressed.</div> -</td> -</tr> -</table> -<ul class="blockList"> -<li class="blockList"><a id="methods.inherited.from.class.java.lang.Object"> -<!-- --> -</a> -<h3>Methods inherited from class java.lang.Object</h3> -<code>clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait</code></li> -</ul> -</li> -</ul> -</section> -</li> -</ul> -</div> - -\end{comment} - -On peut créer cette documentation avec `Maven` par la commande `mvn javadoc:javadoc` ou `mvn site`, si on a ajouté le *plugin* `JavaDoc` (https://maven.apache.org/plugins/maven-javadoc-plugin/usage.html). - -Une telle interface peut être écrite sans que les méthodes soit complètement implémentées, c'est une forme de contrat entre la classe `CalcEngine` et les autres classe du projet. Cette interface doit également faire partie du **cahier des charges**, si la classe est une classe visible par le client. Pour ce projet, elle devrait typiquement être dans le cahier des charges, car le client souhaite utiliser la logique de calcul pour plusieurs projets. - -## Documentation et tests - -Ouvrez le projet `calculator` pour observer les classes. - -Si vous regardez la classe `CalcEngine`, vous pouvez identifier les bonnes pratiques de documentation : - -- Un commentaire de plusieurs lignes au début de la classe pour indiquer le but de cette classe. Vous trouvez aussi les indications d'auteur (`@author`) et de version (`@version`). Vous retrouverez ces informations dans la `javadoc`. -- Chaque méthode de l'interface a un commentaire indiquant son usage, ses paramètres (`@param`) et la valeur retournée (`@return`). -- La mise en page de la classe est consistante, la structure en bloc est bien marquée par l'indentation (vous pouvez utiliser la fonction `mise en page automatique` du menu édition), les accolades sont toujours placées de la même manière. -- Les noms de variables et d'attributs sont bien choisis. -- Les lignes ne sont pas trop longues, les expressions sont aérées. - -Pour vérifier que votre programme respecte les conventions de codage vous pouvez utiliser le programme `CheckStyle` dans le menu `Outils`. Tous les IDE intègrent des outils d'analyse de code et de vérifcation des bonnes pratiques de codage, il est fortement conseillé d'activer ces vérficateurs et de respecter les consignes données pour assurer que votre programme pourra facilement évoluer. - -Pour la partie **test** du programme c'est moins réjouissant, en effet Hacker a créé une classe de test de son cru, plutôt que d'utiliser le *framework* `Junit`, cela peut être une bonne idée dans certains cas notamment pour les tests d'*intégration* (quand on regroupe plusieurs classes ensemble), mais les tests de Hacker laissent faussement penser que le programme fonctionne. Pour apercevoir les dysfonctionnements il suffit pour d'exécuter les méthodes `testPlus` et `testMinus` deux fois de suite. - - -## Débogage - -- - - - -## Travail à effectuer en TP et à la maison - -### Réécriture de `CalcEngineTester` - -Le programme `CalcEngineTester` doit être réécrit sous forme de tests unitaires dans la classe de test `CalcEngineTest`. - -### Déverminage de CalcEngine - -Il y a des erreurs dans `CalcEngine`, vous devez les mettre en évidence et réaliser des tests pour pouvoir les rejouer automatiquement. - -Vous devez corriger la classe `CalcEngine` pour qu'elle passse les nouveaux tests. - -### Compléter les tests - -Vous devez compléter les tests pour testers toutes les fonctions de l'interface. -Assurez-vous que la couverture de code est complète. - -### Réécriture de `CalcEngine` - -Finalement le programme de Hacker T. Largebrain contient trop d'erreurs, on vous demande de réécrire du début la classe `CalcEngine`. -Il faut reprendre la conception dès le début mais les méthodes publiques restent identiques. - -Proposez une conception décrivant le fonctionnement de la calculatrice sous forme de diagramme UML ou de texte écrit. Vous pouvez trouver des exemples sur Internet. - -Mettez en oeuvre votre conception en vous assurant que tous vos tests précédents passent, ajoutez en si nécessaire pour couvrir tout le code. - -- - - +# Projet: calculator + +Auteurs: Michael Kölling and David J. Barnes +Traduction: Laurent Pierron + +Ce projet fait partie du matériel pour le livre + + **Objects First with Java - A Practical Introduction using BlueJ + Fifth edition + David J. Barnes and Michael Kölling + Pearson Education, 2012** + +Il est expliqué dans le chapitre 7. + +Une réalisation d'une calculatrice de bureau. Cet exemple renforce les concepts vus précédemment et est utilisé pour discuter le débogage et le test. +Une version avec une interface graphique est incluse dans la branche `calculator-gui`. + +- - - + +## Préparation du projet + +1. Créer un clone du projet **calculator** sur votre machine. +2. Créez une branche avec votre nom de login. +3. Synchronisez votre branche sur https://gitlab.univ-lorraine.fr. + +- - - + +## Expression du besoin + +On vous a demandé de joindre une équipe chargée de développer une calculatrice logicielle, car un des membres essentiels de l'équipe, Hacker T. Largebrain, a été promu pour diriger un autre projet. +Avant de quitter le projet, Hacker a assuré à l'équipe que vous rejoignez que la réalisation de la partie de calculatrice dont il était responsable était terminée et complètement **testée**. Il a même écrit un logiciel de test pour vérifier que c'était le cas. On vous a demandé de reprendre la classe `CalcEngine` et de vous assurer simplement qu'elle est correctement documentée avant son intégration aux classes développées par les coéquipiers. + + + +Dans l'application des bonnes pratiques de découpage des applications, le projet de calculatrice a été conçu en séparant l'interface utilisateur du moteur de calcul. La première version, que nous étudierons ici, fonctionnera avec une interface graphique (*GUI*) montrée ci-dessous. Plus tard la même calculatrice pourra être utilisée pour créer une application Web et une application pour smartphone. En préparation de cela l'application a été divisée en deux classes : + + 1. `UserInterface` : interface utilisateur graphique, + 1. `CalcEngine` : réalisation de la logique de calcul. + +Hacker était responsable de cette seconde classe. Elle ne devra pas changer quand la calculatrice aura une nouvelle interface. + +Deux autres classes sont présentes pour vous aider à tester la calculatrice : + +1. `Calculator`: programme de lancement de la calculatrice graphique +1. `CalcEngineTester` : programme de test du moteur de calcul, ce programme a été réalisé par Hacker + +## Interface et documentation de `CalcEngine` + +L'analyse du projet de calculatrice a abouti à définir les responsabilités de la classe `CalcEngine` sous la forme d'une liste de méthodes, dont voici la carte de description UML : + + + +```mermaid +classDiagram + class CalcEngine { + + clear() + + equals() + +String getAuthor() + +int getDisplayValue() + +String getTitle() + +String getVersion() + + minus() + + numberPressed(int) + + plus() + } +``` + + +Une fois cette description UML transcripte dans le langage Java, la classe `CalcEngine` devrait avoir une `javadoc` associée, dont une partie est affichée ici : + + + +\begin{comment} + +<!-- ======== CONSTRUCTOR SUMMARY ======== --> + +<section role="region"> +<ul class="blockList"> +<li class="blockList"><a id="constructor.summary"> +<!-- --> +</a> +<h3>Constructor Summary</h3> +<table class="memberSummary"> +<caption><span>Constructors</span><span class="tabEnd"> </span></caption> +<tr> +<th class="colFirst" scope="col">Constructor</th> +<th class="colLast" scope="col">Description</th> +</tr> +<tr class="altColor"> +<th class="colConstructorName" scope="row"><code><span class="memberNameLink"><a href="#%3Cinit%3E()">CalcEngine</a></span>()</code></th> +<td class="colLast"> +<div class="block">Create a CalcEngine instance.</div> +</td> +</tr> +</table> +</li> +</ul> +</section> +<!-- ========== METHOD SUMMARY =========== --> +<section role="region"> +<ul class="blockList"> +<li class="blockList"><a id="method.summary"> +<!-- --> +</a> +<h3>Method Summary</h3> +<table class="memberSummary"> +<caption><span id="t0" class="activeTableTab"><span>All Methods</span><span class="tabEnd"> </span></span><span id="t2" class="tableTab"><span><a href="javascript:show(2);">Instance Methods</a></span><span class="tabEnd"> </span></span><span id="t4" class="tableTab"><span><a href="javascript:show(8);">Concrete Methods</a></span><span class="tabEnd"> </span></span></caption> +<tr> +<th class="colFirst" scope="col">Modifier and Type</th> +<th class="colSecond" scope="col">Method</th> +<th class="colLast" scope="col">Description</th> +</tr> +<tr id="i0" class="altColor"> +<td class="colFirst"><code>void</code></td> +<th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#clear()">clear</a></span>()</code></th> +<td class="colLast"> +<div class="block">The 'C' (clear) button was pressed.</div> +</td> +</tr> +<tr id="i1" class="rowColor"> +<td class="colFirst"><code>void</code></td> +<th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#equals()">equals</a></span>()</code></th> +<td class="colLast"> +<div class="block">The '=' button was pressed.</div> +</td> +</tr> +<tr id="i2" class="altColor"> +<td class="colFirst"><code>java.lang.String</code></td> +<th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#getAuthor()">getAuthor</a></span>()</code></th> +<td class="colLast"> </td> +</tr> +<tr id="i3" class="rowColor"> +<td class="colFirst"><code>int</code></td> +<th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#getDisplayValue()">getDisplayValue</a></span>()</code></th> +<td class="colLast"> </td> +</tr> +<tr id="i4" class="altColor"> +<td class="colFirst"><code>java.lang.String</code></td> +<th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#getTitle()">getTitle</a></span>()</code></th> +<td class="colLast"> </td> +</tr> +<tr id="i5" class="rowColor"> +<td class="colFirst"><code>java.lang.String</code></td> +<th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#getVersion()">getVersion</a></span>()</code></th> +<td class="colLast"> </td> +</tr> +<tr id="i6" class="altColor"> +<td class="colFirst"><code>void</code></td> +<th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#minus()">minus</a></span>()</code></th> +<td class="colLast"> +<div class="block">The '-' button was pressed.</div> +</td> +</tr> +<tr id="i7" class="rowColor"> +<td class="colFirst"><code>void</code></td> +<th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#numberPressed(int)">numberPressed</a></span>​(int number)</code></th> +<td class="colLast"> +<div class="block">A number button was pressed.</div> +</td> +</tr> +<tr id="i8" class="altColor"> +<td class="colFirst"><code>void</code></td> +<th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#plus()">plus</a></span>()</code></th> +<td class="colLast"> +<div class="block">The '+' button was pressed.</div> +</td> +</tr> +</table> +<ul class="blockList"> +<li class="blockList"><a id="methods.inherited.from.class.java.lang.Object"> +<!-- --> +</a> +<h3>Methods inherited from class java.lang.Object</h3> +<code>clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait</code></li> +</ul> +</li> +</ul> +</section> +</li> +</ul> +</div> + +\end{comment} + +On peut créer cette documentation avec `Maven` par la commande `mvn javadoc:javadoc` ou `mvn site`, si on a ajouté le *plugin* `JavaDoc` (https://maven.apache.org/plugins/maven-javadoc-plugin/usage.html). + +Une telle interface peut être écrite sans que les méthodes soit complètement implémentées, c'est une forme de contrat entre la classe `CalcEngine` et les autres classe du projet. Cette interface doit également faire partie du **cahier des charges**, si la classe est une classe visible par le client. Pour ce projet, elle devrait typiquement être dans le cahier des charges, car le client souhaite utiliser la logique de calcul pour plusieurs projets. + +## Documentation et tests + +Ouvrez le projet `calculator` pour observer les classes. + +Si vous regardez la classe `CalcEngine`, vous pouvez identifier les bonnes pratiques de documentation : + +- Un commentaire de plusieurs lignes au début de la classe pour indiquer le but de cette classe. Vous trouvez aussi les indications d'auteur (`@author`) et de version (`@version`). Vous retrouverez ces informations dans la `javadoc`. +- Chaque méthode de l'interface a un commentaire indiquant son usage, ses paramètres (`@param`) et la valeur retournée (`@return`). +- La mise en page de la classe est consistante, la structure en bloc est bien marquée par l'indentation (vous pouvez utiliser la fonction `mise en page automatique` du menu édition), les accolades sont toujours placées de la même manière. +- Les noms de variables et d'attributs sont bien choisis. +- Les lignes ne sont pas trop longues, les expressions sont aérées. + +Pour vérifier que votre programme respecte les conventions de codage vous pouvez utiliser le programme `CheckStyle` dans le menu `Outils`. Tous les IDE intègrent des outils d'analyse de code et de vérifcation des bonnes pratiques de codage, il est fortement conseillé d'activer ces vérficateurs et de respecter les consignes données pour assurer que votre programme pourra facilement évoluer. + +Pour la partie **test** du programme c'est moins réjouissant, en effet Hacker a créé une classe de test de son cru, plutôt que d'utiliser le *framework* `Junit`, cela peut être une bonne idée dans certains cas notamment pour les tests d'*intégration* (quand on regroupe plusieurs classes ensemble), mais les tests de Hacker laissent faussement penser que le programme fonctionne. Pour apercevoir les dysfonctionnements il suffit pour d'exécuter les méthodes `testPlus` et `testMinus` deux fois de suite. + + +## Débogage + +- - - + +## Travail à effectuer en TP et à la maison + +### Réécriture de `CalcEngineTester` + +Le programme `CalcEngineTester` doit être réécrit sous forme de tests unitaires dans la classe de test `CalcEngineTest`. + +### Déverminage de CalcEngine + +Il y a des erreurs dans `CalcEngine`, vous devez les mettre en évidence et réaliser des tests pour pouvoir les rejouer automatiquement. + +Vous devez corriger la classe `CalcEngine` pour qu'elle passse les nouveaux tests. + +### Compléter les tests + +Vous devez compléter les tests pour testers toutes les fonctions de l'interface. +Assurez-vous que la couverture de code est complète. + +### Réécriture de `CalcEngine` + +Finalement le programme de Hacker T. Largebrain contient trop d'erreurs, on vous demande de réécrire du début la classe `CalcEngine`. +Il faut reprendre la conception dès le début mais les méthodes publiques restent identiques. + +Proposez une conception décrivant le fonctionnement de la calculatrice sous forme de diagramme UML ou de texte écrit. Vous pouvez trouver des exemples sur Internet. + +Mettez en oeuvre votre conception en vous assurant que tous vos tests précédents passent, ajoutez en si nécessaire pour couvrir tout le code. + +- - -