Reef

[Projects] [Publications] [Contact]

 

For the latest status updates on Reef's development, visit my R&D blog.
For a more formal and detailed account of Reef, you can read my research proposal, or take a look at the PowerPoint presentation.
Questions, criticisms, encouragement, offers of collaboration or financial support? Send them all my way!

Reef is an autonomic scribe that captures design information (in the form of UML diagrams) during the development process of an object-oriented application. Reef is different from typical modeling tools:

  • it's a zero-install thin client that fits into the developers' existing workflow;
  • it considers source code to be the ground truth;
  • it believes that diagrams are a means of communication and must be at a higher level of abstraction to be useful;
  • it takes responsibility for keeping the diagrams up-to-date, communicating with team members as necessary.

The developer Step 1 The repository
A UML diagram
Step 3 Step 2
Step 6 Step 4
Reef's back-end
Documentation
Step 5
Development Workflow Using Reef
Click on parts of the diagram for an explanation of Reef's workflow, or start with Step 1.
The Developer
A developer is anyone who edits the source code of the object-oriented application. Reef is most suitable for small to medium-size, co-located or distributed teams following an agile development process with little up-front design. Reef initially supports Java applications and UML design diagrams, but could be adapted to work in other settings.  Within those constraints, Reef follows adoption-centric principles by adapting to the developer's preferred tools and workflow.
The Code Repository
A code repository holds versions of the source code and other resources that punctuate the evolution of the application. Initially, Reef supports file system and CVS stores, but can be extended with other version control system adapters.
Reef's Back-End System
Reef's back-end runs a continuous autonomic control loop on the server, regularly checking the repository for changes, publishing updated documentation, and interacting with team members through diagram agents. It stores data in an embedded XML database and accepts plug-ins at well-defined extension points.
A UML Diagram Agent
UML diagrams are rendered in SVG 1.2 and pack their own browsing and editing facilities (programmed in ECMAScript). Since they are self-contained, requiring only an SVG viewer to be displayed, they can be transmitted freely to and edited by any interested parties without worrying about installing a special-purpose diagramming tool. The agents can operate in both on-line and off-line environments, automatically tailoring their features and communication techniques.
Application Documentation
The documentation set generated by Reef cross-references the design-level diagrams with implementation-level descriptions (e.g. Javadocs) and possibly the source code itself. The documentation also includes a variety of metrics related to the source code, the diagrams, and the development and documentation process.  (For example, it would be possible to see which diagrams are most in need of ratification, or who has been remiss in their documentation duties.)
Step 1: Commit the Source Code
The developer commits some changes to the application's source code to the repository, using their favourite tool, unaffected by (and possibly even unaware of) Reef. It is advantageous if the commits follow best practices by including an appropriate message and being applied in small, cohesive chunks, but Reef will adapt to less disciplined approaches as well.
Step 2: Update the Design Diagrams
When Reef detects that the application's source code has changed in the repository, it checks out an up-to-date version and, by means of reverse-engineering techniques, propagates the modifications to the application's design model. The update process is incremental, so that reasonably sized commit sets can be handled quickly even for large applications. Furthermore, updates to the UML diagrams extrapolate previous adjustments made by the editors (see Step 4) to reduce their workload, and do not unnecessarily change the layout of the diagram to preserve the readers' mental map of the design.
Step 3: Request Diagram Ratification
Any UML diagrams that have sustained non-trivial changes are sent by Reef to the appropriate editors with the changes highlighted. Email is the preferred transport mechanism, due to its features (e.g., authentication, off-line availability) and universal cognitive support, with instant messaging, RSS and manual web page polling rounding out the picture. By default, a diagram is sent to the developer responsible for the majority of the relevant changes, but the recipient can delegate the responsibility by forwarding the message to somebody else. Whoever finally ratifies the diagram becomes its editor and is implicitly added to the development team, thus enabling a viral spread of the tool. If the diagram is not ratified for a long time, Reef may decide to resend the request to the same or another editor.
Step 4: Ratify the Design Diagrams
Editors fix the diagrams and ensure that they provide an accurate and useful representation of the application. Human involvement is necessary since some design-level properties are diffused beyond recognition in the implementation, making them unrecoverable by automated reverse-engineering techniques. Furthermore, an editor makes important decisions about what to elide from the diagrams to maximize their communicative value. To make the editor's job easier, the diagram indicates any reverse-engineered changes and links them to commit set comments and ultimately to the source code. Any edits can also be amplified, teaching Reef by example how to improve future diagrams. When the editor is satisfied with the diagram, he ratifies it and submits it back to Reef.  Although ratifying a diagram should only take a few minutes, the editor can also delegate the task (see Step 3), postpone it, or obsolete the diagram altogether.
Step 5: Publish the Documentation
As ratified diagrams pour back into Reef's back-end, they are embedded into the application's documentation and published to a web server. Team members are notified of updates to diagrams (if so requested), enabling them to track the evolution of the application at a higher level of abstraction than the raw repository change logs would, increasing the team's awareness.
Step 6: Browse the Documentation
At any time, team members can browse the application's documentation. All documentation is cross-referenced, so there's no need to decide a priori whether implementation or design documentation is relevant to the problem at hand. The ratified UML design diagrams are time-stamped and version-stamped, so that developers can be confident they're not stale; if the browser is running in on-line mode, a diagram can even report how well it matches the current source code. Finally, all the diagrams are still self-editable, so readers can make opportunistic corrections if so authorized.