Development Workflow Using Reef
Click on parts of the diagram for an explanation of Reef's workflow, or start with Step 1
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
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
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
for changes, publishing updated
, and interacting
with team members through diagram
. It stores data in an embedded
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
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.
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
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
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
, 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
), 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
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
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.