Skip to content
Software Architecture Guide

Undetected Duplication Antipattern

Explanation

Section titled “Explanation”

Documentation can describe the same thing in more than one place. The arc42 template (see arc42 Architecture Documentation Template) takes this seriously. Its guidance asks how to avoid documenting or specifying the same interface redundantly at several places in the building block view. It also says near-identical repeated refinements, meaning more detailed breakdowns of a building block, are too much redundancy.

Remedies

  • Describe once, reference elsewhere. Give the detailed description only where the element is actually handled. At every other occurrence, add a reference to that description.
  • Keep other occurrences short. In the context view, give the element a short, fitting name and its business relevance. Keep the detail elsewhere. See Context View.
  • Factor out repeated structures. If the same substructure recurs in several refinements, move it into a crosscutting concept (see Crosscutting Concept). Stereotypes that point to that concept give a leaner structure without the repetition.

The principle behind it

The DRY principle (short for “don’t repeat yourself”) says every piece of knowledge needs one single, unambiguous, authoritative representation. Its authors apply this broadly, including to documentation. A duplicated entry breaks this rule, because a reader cannot tell which entry is the authoritative one. A single source of truth restores it.

Example

Section titled “Example”

An overview of a hypothetical booking service lists “Cancel Booking” in two places. Both entries sit in the same overview. The remedy is to keep the detailed description in the one place where cancellation is handled. The other entry gets a short name and a reference to that description.

Trade-offs

Section titled “Trade-offs”

References replace repeated text, so readers must follow a link to find the detail. In return, there is one authoritative description to maintain. The facts given here do not say more about costs.

Checks

Section titled “Checks”
  • Each interface or element is described in detail in only one place, and other occurrences reference it.
  • Elements shown in the context view have a short name and business relevance, with detail kept elsewhere.
  • Recurring substructures across refinements are factored into a crosscutting concept instead of repeated.
  • Each piece of knowledge in the documentation has a single authoritative representation.
Section titled “Related”

Sources

Section titled “Sources”