3 Global Understandability

When authoring a narrative in Java, imagine the potential reading audience.  Such a narrative—your code—may be durable for decades.


Based on experience with “the Company,”[1] we assert that software “global understandability” is aided by: gauging the (code) reading ability of current and future readers, techniques for expressing code structure, the incorporation of business context when naming Java constructs, and overcoming a limitation of pair programming.

We have witnessed first-hand the emergence of global sourcing as an impediment to the co-location ideal represented by Todd’s[2] team. Can anyone have confidence regarding who will maintain their applications in five or ten years? What native languages will they speak? Where will they reside? What cultural contexts will shape their technical and business views? How much will the enterprise be willing to invest in software engineering talent?

A team adage, such as “Write Once, Read Many,” is a useful reminder that application code has a longer shelf life than first imagined, and a diverse readership — well beyond the original development team.

We agree with the spirit of the notion that “source code is living documentation.” Accordingly, PED seeks to incorporate a convention that enhances the capacity of code to communicate its structure to a reader. We dub our technique “Pattern Encoding,” where an applied pattern is denoted by a suffix. For example, the NoteDE class is recognized as an implementation of the Domain Entity pattern based on its suffix DE.[3]

In the early days of information systems, COBOL (COmmon Business-Oriented Language) was intended as a tool for the automation of business processes. COBOL syntax is intentionally verbose, reflecting its designer’s desire for readability (by both technical and non-technical staff), with English-like syntax and structural elements, such as nouns, verbs, clauses, sentences, etc.

Java, as an intentionally more general-purpose language, has neither the English-like grammatical structure nor the incorporation of English business operations into its language elements. To compensate for its native lack of readability, the communication of business-related functionality in Java relies on the software engineer to effectively name classes, methods, and variables.

We encourage thinking about source code, including JUnit test code, as a business narrative for humans, not compilers.  When that kind of thinking occurs, we get code that is understandable in the sense that it reveals the business narrative when read. Martin Fowler (1998) is more direct: “Any damn fool can write code that a computer can understand. The trick is to write code that humans can understand.”[4]  Moreover, if business domain knowledge cannot be gleaned by reading the code, the ability of software engineers to move from project to project suffers.

While we appreciate the value of standard practices employed to facilitate understandable code – pair programming in particular – they arguably are inadequate for long-term global readability of enterprise source code. Pair programming, and even a team code review, sometimes demonstrates a kind of parochialism – the native dialect of the current team. That is, teams will evolve to using shorthand communication mechanisms (e.g., acronyms) and the assumptions that go with “team-speak” find their way into the source code.

The antidote is a viable Pattern Palette derived from a more universal language. While some team idioms are inevitable, we prefer code when its dialect is intelligible to engineers on other teams.


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

[2] Todd Hall was technical lead and architect for the original 2004 team launching the PED journey.

[3] Despite superficial similarities with Hungarian notation, none of the well-rehearsed objections to that convention apply to Pattern Encoding.

[4] Fowler revised this to “Any fool can write code that a computer can understand. Good programmers write code that humans can understand” in later publications.

Fowler, M. 1998. After the Program Runs. In Distributed Computing (September).