7 Reference Application

The seventh principle seeks to harmonize enterprise communication:
When promoting application architecture, design or implementation recommendations, establish a reference application as an alternative to comprehensive documentation.

Reference

Based on experience with “the Company,”[1] we submit that a “reference application” can: demonstrate an Adaptable Technology Wrapper (ATW) in the context of a deployable application, promote synergy among distributed teams, and support informal discovery as an alternative to extensive written documentation.

In late 2006, our CEO championed collaborating as “one team.” We were prompted to ask, how could we globalize a common set of patterns to hundreds of developers on project teams spread across six continents? How do we foster the broad adoption of a pattern mindset among dispersed individuals?

Norms governing “teamful” behavior are widely accepted for project teams of “seven-plus-or-minus-two.” While individuals have one set of commitments as part of small self-organizing work groups, could they have a different set when they regard themselves as members of an enterprise team? When conditions require the scaling of teamful behaviors to 70 ± 20, or even 700 ± 200 developers, a software engineering safety hazard emerges: that of divided allegiance.

A reference application can help mitigate this hazard; when multiple teams compare their code against a prevailing standard, that process tends to “normalize” designs and implementations. A reference application helps pave the way for interoperating as that elusive “one [global] team.”

Beginning in 2002 with the adoption of Java, there was an initial bias for written English-language documentation as a tactic for communicating software design guidelines to the enterprise development community. There was continual angst over whether or not code examples should be maintained within this documentation, and whether the code examples should be use-case independent or share a similar context.

Comprehensive written documentation never seems to resolve the age-old dilemma: its statements are either too abstract to provide implementation guidance, or too specific to be maintainable. If written documentation becomes subordinate to a learning example implementation, it can focus on guiding the learner through the structure of the application and the manifest patterns, within the context of a user story that grows increasingly familiar with exploration. Additionally, investment in authoring comprehensive documentation in the form of software design guidebooks depreciates rapidly with technology obsolescence.

As a technical communications tool, Java and its allied languages (CSS, JavaScript, XML, etc.) offers a degree of precision unmatched by natural languages. When promoting enterprise team behaviors among developers, why not use their lingua franca? Others have arrived at a similar conclusion:

One of the most requested aids to coming up to speed on DDD [Domain Driven Design] has been a running example application. Starting from a simple set of functions and a model … we have built a running application with which to demonstrate a practical implementation of the building block patterns…[2]

References

[1] In 2002, Java was adopted as the standard platform for in-house development at a successful large automotive manufacturing enterprise (“the Company”).

[2] http://dddsample.sourceforge.net