7 Reference Application

When seeking application architecture, design or implementation recommendations, use a a reference application as an alternative to comprehensive documentation.


Based on experience with “the Company,”[1] we submit that a “reference application” can: 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.” Almost concurrently “the Company” embraced global (low-cost) sourcing. How does one foster the broad adoption of a pattern mindset among dispersed individuals on six continents?

Norms governing “teamful” behavior are widely accepted for co-located project teams of “seven-plus-or-minus-two.” When conditions require the scaling of teamful behaviors to 70 ± 20, or even 700 ± 200 globally distributed software engineers, a 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 design and implementation. A reference application helps pave the way for interoperating as that elusive “one [global] team.”

Comprehensive written documentation alone never seems to resolve an age-old dilemma: its statements are either too abstract to provide implementation guidance, or too specific to be maintainable. However, when written documentation becomes subordinate to a reference application, the learner can absorb application structure and manifest patterns within the context of a user story that grows increasingly familiar with exploration.

As a technical communications tool, Java and its allied languages (CSS, JavaScript, XML, etc.) offer a degree of precision unmatched by natural languages. 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]


[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