christopher oezbek ag software engineering fu berlin 28.11.2005 christopher oezbek,...

Christopher OezbekAG Software EngineeringFU Berlin28.11.2005

Christopher Oezbek, [email protected]

JTourBus

Christopher Oezbek, [email protected] 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?)


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!


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


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].


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


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)


Applications can be based on it


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


AspectJ PointcutHandlerAspect


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 ;-)


JTourBus TourStop


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?


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?


The same using the Tourbus...

• A simple transform into a tour.

• Tried to stick to the info given.

• Added an ordering.


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.


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.


Mylar [KerMur05]

• By the navigation of the user a relevant subset is selected and subsequently presented.

• No documentation, just easier comprehension of concerns.


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


JTourBus uses JTourBus


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:

1. Use AST Supports Annotations but no incremental compile, slow

2. Use JavaModel Fast, lightweight, fault-tolerant, incremental, not the right granularity (javadoc, annotations not part of the model)

3. 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]


Demo


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?)


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.


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


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


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


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?


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.


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.


Concerns

• Undo Concern

• Draw Concern

• Update Strategy Concern

• Multi-View Concern

• Drag and Drop Concern

• Persistence Concern


Idea I: Fix Zooming


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


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.


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?


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...


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


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


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)


Thank you!


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


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.


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


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.


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...


Environment

• Eclipse

• Online-API documentation

• Screen-capture Record special events.

• Questionnaire system

• ECG-instrument to measure:• Usage of JTourBus and design documentation• Browsing, etc.


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.

christopher oezbek ag software engineering fu berlin 28.11.2005 christopher oezbek,...

Documents

jtourbus slide

ajhotdraw deumarmoo05

sourcecode difficult

unity of source

javadoc documentation

main role of documentation

jhotdraw exercise

delocalization wilde