JTourBus

1. JTourBus

2. Motivation • Software Documentation is difficult and time-consuming to do, yet essential for reducing maintenance-costs. • The main role of documentation is to facilitate understanding of the software internals. • JTourBus is supposed to be the tool-centric, developer-side innovation in my thesis: • Improve understandability / discoverability! • After we have empirically validated the approach: • Introduce into OSS Java project as an diffusion of innovation exercise (see talk in January) • (Perform industry trial?)

3. Why is the source not enough? • Because problem/concern is separated from solution/implementation by the structure of the program. • Also called "Delocalized plan" [SolLet86] • Example: "Personal Database" • Deleting an entry does not remove it from the data-structure but merely sets a delete-flag. • The maintenance task of providing an undelete operation was often implemented by searching for the entry and unsetting the flag. • Problem: The search used the deleted-flag to return only non-deleted entries. •  The plan/concern of how to delete entries was delocalized!

4. What to do? • An idea: Aspect-Orientation [Kiczales et al. 2001] • Concerns crosscut programs • Thus extract the implementation of a concern and condense it into an aspect. http://www.javaworld.com/javaworld/jw-01-2002/jw-0118-aspect.html

5. OO and Delocalization • Object Orientation has two additional features in comparison to procedural languages that contribute to delocalization [Wilde et al. 92,93] • Inheritance • Polymorphism / Dynamic Dispatch • Code reviews get substantially harder in the face of delocalization [DunRopWoo00]. Remember P-SWT? • But can OO not help to separate concerns? Use of classes, etc? • OO approaches usually are only capable of capturing one concern separation and usually this separation is used to model the problem domain. • "tyranny of the dominant decomposition" [TarOssHar99].

6. Existing Alternatives • Don't try to mess with the code but improve understandability! • JavaDoc (documentation embedded in source to create API references): • Unity of source and documentation  Spatial locality • Restricted context  Methods and classes seldom depict use in a wide context (Anybody knows the Use-page?) • Design documents (UML or textual, often custom notations) • Provides context and relationsships. • Separated from Source-Code  Difficult to keep up-to-date • Binary fileformat  Versioning difficult

7. Our main example: JHotDraw • Exercise in a pattern-seminar • Design-pattern centric • Thomas Eggenschwiler and Erich Gamma • 338 classes • Clean division in 26 framework interfaces and numerous implementations: • Interface Tool • SelectionTool • PolygonTool • ConnectionTool • Aspect Oriented Version of JHotDraw: • AJHotDraw (DeuMarMoo05)

8. Applications can be based on it

9. A coarse concern: Handler handling • Figures have different implementations of the handler interface. • Handlers have visual representations and need to be included in the mouse-handling. • 22 of the 338 classes need access to the handle interface, 16 sub-classes. • Many accesses are hidden behind layers of design patterns, e.g.: • AbstractFigure offers a Visitor-Pattern • Handles will be enumerated and visited as well • Problem: No FigureVisitor implements visitHandle

11. AspectJ HandlerAspect Pointcut

12. Alternative JTourBus • Create a network of implementation-locations with regards to a problem. • Implementation centric • Easy integration into existing systems • Code unmodified (=> JavaDoc tags) • Use way-points to create linear structures  thus called "Tour" • Granularity: > Method Yes it kind of looks like a rabbit ;-)

13. JTourBus TourStop

14. Let's compare to UML! • Nice, fast overview. • Sufficiently standardized. • What does the black dot mean? • Not code based. • Called DrawApplication in current JHotDraw-Version • Easier to neglect due to missing compiler checks. • For instance 3 Change-Logs: • change_log.txt • ReleaseNotes.html • Changes.html • Do we now know howJHotDraw works?

15. A Hypothesis? • "Programming-tools need to be based in human-readable, source-code close, compileable/runnable file-formats." • See JavaDoc • See UML / MDA • See Make / Ant • Everything else gets rejected. • CVS the main impediment?

16. The same using the Tourbus... • A simple transform into a tour. • Tried to stick to the info given. • Added an ordering.

17. Related Work (1) • JavaDoc See-Tag: • Tool-Support only after compiliation (HTML) • Installation of refs difficult (qualified target-name needed) • Tours can not be build • JavaDoc Uses-Page: • Displays all occurrences of a given type in signatures and inheritance structures. • Not selective. • Prone to Implementation/Interface problem.

18. FEAT [RobMur02] • (Feature Extraction and Analysis Tool) • Methods can be grouped into concerns and thus navigated to more easily. • Not code-centric (for instance last version did not store data persistently) • Formulation of concern-sets (unstructured) is central.

19. Mylar [KerMur05] • By the navigation of the user a relevant subset is selected and subsequently presented. • No documentation, just easier comprehension of concerns.

20. JTourBus w/o Buzz Words • Named, ordered code-locations that can be navigated to using an IDE • Code centric • CVS compatible • Close to the implementation • Familiar syntax (@JTourBusStop) • What it is not: • Task aware • Personal • Automated

21. JTourBus uses JTourBus

22. Implementation details • Eclipse 3.1-Plugin • Alternative approach: Annotations (Java 1.5) • @JTourBusStop(stop=0.0, route="Main Route", description="Program entry point") • Inflexible, verbose • Rely on the Eclipse-API for all heavy lifting • Three different approaches: • Use AST  Supports Annotations but no incremental compile, slow • Use JavaModel  Fast, lightweight, fault-tolerant, incremental, not the right granularity (javadoc, annotations not part of the model) • Use Search + JavaModel.changeNotifications  Wicked fast, Regular Expression based, incremental, fault-tolerant, no annotation-support • Eclipse-View with DND- and progress-Support. • Best literature for hacking eclipse: [AesBäuLan05]

23. Demo

24. Now  Empirical validation • Is it needed? • (Assuming the software crisis is not over yet) YES • Usable? • Pilot-test • Comparing to the alternatives? • JTourBus as a documentation reader • JTourBus as a documentation tool •  Controlled experiment • (  Later: Trial in an industry setting?)

25. Controlled Experiment • Recall the lecture from Empirical Methods in Informatics: • Control • Achieve constant values with variables we are not interest in. • Dependent Variables • Those variables we want to see a difference in. • Independent Variables • Those variables we change on purpose to observe difference in the dependent variables. • Internal Validity • We can be confident to find similar results if we repeated the experiment. • External Validity • The results will transfer to other contexts.

26. Variables • Independent: • Documentation Method: • J: JTourBus • U: UML • Dependent Variables: • P: Percentage of correct answers • T: Time per Question • D: Documentation reading time / JTourBus uses • Used to distinguish the "Lone Hacker" • C: Subjective Confidence in Answers

27. Design • Subjects: • Fifth Semester Students • Following ALP3, SWT. • Theoretical part should have been taught. • Task as part of an exercise: • Internal Validity: Motivation? • Internal Validity: New == Cool, Tool == Cool? • 90 minute task in the computer labs • Randomized, Counterbalanced-Design

28. Counter-Balanced-Design • Compare two methods J and U. • Want to achieve control over: • Individual differences  Each student has to use both methods  Need to tasks (S und T) • Differences due to the tasks  Each task has to be done with both methods. • Learning  Both orders have to been done. • Four groups: JS  UT, US  JT, JT  US, UT  JS • Randomization = Assign participants randomly to the 4 groups. • No Matching • 20 persons/group  80 participants

29. External Validity • Realistic problem size: • JHotDraw is not tiny. • How to ensure that the created documentation J and U are similar enough? • Let students create the documentation given a certain amount of time. • Possible alternatives: • 4 Students. Each of them creates one of JS, JT, US, UT. • 4 Students work together and create JS, JT, US, UT. Are told to ensure same content. • 8 Students ensure a little control over individual differences. • Half the available students: • Pick best or not?

30. Running the experiment • Prepared accounts on the computers • Distribute task description. • Participants read tasks and may ask questions using a FAQ • 90 minutes time limit • Help only with technical problems • Thesis worker would be great! • Answering questions using a online-questionnaire.

31. The task • The most important part: • Requirements: • representative, realistic  not to small. • reduce dependence on other variables (e.g. previous knowledge  JHotDraw was featured on exercise sheets in ALP3) • doable  Limit to 90 minutes, not overly complex • Would be great to use an existing set of question about architecture, reverse engineering.

32. Concerns • Undo Concern • Draw Concern • Update Strategy Concern • Multi-View Concern • Drag and Drop Concern • Persistence Concern

33. Idea I: Fix Zooming

34. Fix Zooming • Display not correct • UpdateStrategy not set correctly • UpdateStrategy not implemented correctly • Application is responsible for setting UpdateStrategy on View. • MouseCursor does neither indicate that zooming is selected (magnifier) nor provide feedback (-,+) • Follow Mouse/Key Events from DrawingView into Tool • Architectural easy • Implementation details are complicated

35. Idea II: Change default colors • All objects created with JHotDraw have a default color, which can only be changed subsequently by another tool. • Tools encapsulate some state information (enabled/disabled, etc.), but there is no possibility of interaction between tools. • Basically two architectural solutions: • Allow access to the prototypical figure inside CreationTools from which newly created figures are cloned. • Not all figure tools are based on CreationTool • Apply the ChangeAttributeCommand after any tool finished to the added figure. • There is no solution without changing visibilities of methods.

36. Idea III: Command vs. Tool • JHotDraw differentiates tools and commands • Tools are selected and then used on the drawing (e.g. to create a figure). • Command execute when being clicked (say change color). • Both tools and commands can be undone, but there is only one undo-stack. How does it work?

37. Idea IV: Drawing • When the user uses a tool to create a new figure, the figure is drawn before finishing creation. • How does this work? • The tool adds itself to the drawing in the beginning. • No way to cancel any more. • Drawing works in magically ways if one forgets about AWT/Swing...

38. Short Overview: • DrawingView is a JPanel, thus receives call to paintComponent, which is redirected to a Painter • Painter calls drawAll() on DrawingView • ... Some complicated background drawing stuff... • DrawingView.drawDrawing() calls draw on the Drawing • The Drawing itself does not have a draw method, but inherits the one from CompositeFigure! X-) • CompositeFigures then call draw on all figures they are composed of. • A typical figure.draw calls drawBackground und drawFrame which actually do the drawing. •  Stack depth at this point 24: 7 EventDispatching, 8 paintXXX, 3 drawXXX, 6 draw

39. How to find this out?  Manually • Tracing? • Takes forever without good IDE • Even good IDEs struggle due to interface/ implementation separation • Debugger? • Smart nice solution, if you know where to start. • UML/Sequence Diagrams? • Contain all the information • Pretty right-balanced • JTourBus? • The killer-app for JTourBus  Visit stops fast and convenient, skip boring parts • Somebody has to write the documentation and keep it up to date

40. Creating the documents/Pilot-Test • Maximizing knowledge gained from actually making both types of documents. • Qualitative Data gathering • Looking for participants! • Anybody interested? 90 minutes? Counts as a visit in the seminar? • You would be given the tasks to document the system using one of the two systems. • Quantitative M.: Time, coverage • Qualitatively comparison (quality, enjoyment)

41. Thank you!

42. Example • How to design: • Left side treeview, right side editor view • Select on treeview changes right side • Often forgotten: • Changes in the editor also change treeview. • Bidirectional access needed. • Often complicated notifier-architecture

43. General Problems of this approach • Problems can become very easy when the right documentation (both UML and JTourBus) is provided. • Are we just hiding a problem, when we selectively provide documentation that matches the problems closely? • How much to reveal of each problem? • Drawing can be explained so well, that there is no task there any more.

44. General Problems of using JHotDraw • Basically unusable software  Academic exercise • Lightyears removed from serious published software  Inkscape • Package structure seriously damaged by outside contributions: • org.jhotdraw.util • org.jhotdraw.standard • org.jhotdraw.contrib • If one learns anything from JHotDraw  As computer scientists we are incapable of even building a drawing editor in a sound way. • Design patterns not sufficient to explain how to implement common metaphors like "Editor" • Solution for the concert of all concerns not given: • Persistence, Undo, Tool, State, Multi-View

45. Alternatives? • Any good Java programs out there? • All Eclipse based (SWT): • RSSOwl (RSS Reader) • Azureus (BitTorrent client) • Architecture needs a lot of explaining: OSGi • Might find J2EE applications that are usable  Difficult for students w/o J2EE background • APIs? • GJDoc • Editors? • DrJava • Problem: • Very good programming skills absolutely essential.

46. Example if we would use Eclipse • Typical code to get all compilations unit of a single project (also called a "Jungloid" ManXuBod05): • High risk to lose all students in the Jungle...

47. Environment • Eclipse • Online-API documentation • Screen-capture  Record special events. • Questionnaire system • ECG-instrument to measure: • Usage of JTourBus and design documentation • Browsing, etc.

48. A documentation tool? • Indeed the code will not be improved. • Concern code is not co-located (or even unified) as with AspectJ. • Speaking figuratively: • If code pieces of a concern are like a family then it might not always be a good idea to have the mother-in law living with you. • To have her within a trip's reach on the other hand, might not be bad either.