A Team Pattern Catalog: Adding, Changing and Retiring

Once a team has a handful of pattern cards, they drift: two contradict, one describes how things used to be done, and new teammates copy whatever they find first; a catalog keeps every card in one place with a status, changes cards through review with a short decision record, and retires old patterns without deleting them.

Freelancer · Software Development · OOP · Updated

By

After this lesson you can

  • Keep a team pattern catalog where each card has a status and every change goes through review
  • Retire a pattern without deleting it: mark it, name what replaces it, and catch new uses

Key takeaways

  • A catalog is the team's cards in one findable place, kept beside the code and changed the way code is: through review.
  • Each card has a status: proposed (new, being tried), current (use it) or retired (don't, and here's what replaces it).
  • A decision record explains why a card was added, changed or retired: the situation, the decision and what it costs.
  • Retire a pattern without deleting it: mark it, name what replaces it, and let a check catch new uses.

Before this: Writing a Pattern Card Your Team Will Read.

A year on, Summit Gym's teams have nine pattern cards on a wiki page. Two of them disagree about where booking rules belong. One, "Ask GymManager", describes the way the old code works: every screen asks one giant GymManager class for prices and bookings. The team decided months ago to stop doing that, but the card still sits there looking current, and new teammates copy the pattern, because it's what they see all over the old code. Nobody is sure which cards to trust. A pile of cards isn't a catalog yet; by the end of this lesson you'll know what turns it into one.

The symptom: cards nobody trusts

  • The symptom: cards that contradict each other, old patterns still copied into new code, and nobody sure which cards are current.
  • The cause: each card was written once and never owned. No card says whether it's still the way to do things, changes aren't reviewed, and nothing records why the team changed its mind.
  • The cure: a catalog: the same cards, with a status, a review, and a record of each decision.

What would you try?

Delete the old cards. The old code still uses those patterns. The next person who opens a screen full of GymManager calls has no explanation, and the reason it was replaced is lost.

A meeting to agree on them all. Decided once, forgotten by next year, and every new teammate missed it.

Lock the wiki page. Then it can't change when the code does, and it drifts further every month.

What we want: one place, a status on every card, changes reviewed and explained, and old patterns marked rather than erased.

Where the catalog lives

Keep the cards in the code's repository, one short file per card in a folder such as docs/patterns/, with an index page that lists each card's name, its one-line problem and its status. Then a change to a pattern and the change to the code it describes go through the same review, and the cards are versioned with the code they describe.

Each card has a status:

  • proposed: a new card, being tried in real code;
  • current: the way to do it now;
  • retired: don't use it in new code, and here's what to use instead.

A team's pattern catalog in three groups: proposed (Waitlist Reminder), current (Row Importer and Booking Service) and retired (Ask GymManager, grayed out, "use Booking Service instead"). A card moves from proposed to current once reviewed, and to retired once replaced

Adding and changing a card

A new card starts as proposed. Once the pattern has been used for real (remember the rule of three) and the team has reviewed it, it becomes current. A card changes in the same pull request as the code change it describes, so they can't drift apart.

Each decision gets a short decision record, often called an architecture decision record (ADR), an idea Michael Nygard wrote up in 2011. It's a small file that says:

  • the title and status (proposed, accepted, or replaced by a later record);
  • the context: what's happening, and why a decision is needed;
  • the decision: what the team will do;
  • the consequences: what it costs, and what it makes easier.

Here is the record behind one of the gym's decisions:

Retire "Ask GymManager" · Status: accepted

Context: Every screen asks GymManager for prices and bookings. It has grown to do everything, and every change touches it.

Decision: New code asks BookingService instead. The "Ask GymManager" card is marked retired, pointing to the "Booking Service" card.

Consequences: Old screens keep working; each one moves to BookingService the next time it's changed. For a while, both ways are in the code.

A record isn't rewritten later. When the team changes its mind again, it writes a new record that replaces the old one, so the history of why stays readable.

Retiring a pattern

Retiring a pattern takes three steps:

  1. Mark the card retired, with what replaces it and a link to the decision record.
  2. Keep the card. Old code still uses the pattern, and whoever reads that code needs to know why it's there and what to use instead.
  3. Catch new uses with a check that runs before code is merged.

Here's that check at its smallest: the catalog as data, and a teammate's new code checked against the retired cards:

// The team's catalog: each card's name, its status, the text that shows it's being used, and what replaces it.
List<Card> catalog = new List<Card>
{
    new Card("Row Importer", "current", "ImportRows(", ""),
    new Card("Ask GymManager", "retired", "GymManager.", "BookingService"),
    new Card("Waitlist Reminder", "proposed", "", ""),
};

foreach (Card card in catalog)
{
    Console.WriteLine(card.Status == "retired" ? quot;{card.Name}: retired, use {card.Instead} instead" : quot;{card.Name}: {card.Status}");
}

// A teammate's new code, checked before it's merged.
string[] newCode =
{
    "Member maya = members.Find(\"Maya\");",
    "int price = GymManager.PriceOf(maya);",
    "List<Member> rows = ImportRows(text, MakeMember);",
};
for (int number = 1; number <= newCode.Length; number++)
{
    foreach (Card card in catalog.Where(card => card.Status == "retired" && newCode[number - 1].Contains(card.Marker)))
    {
        Console.WriteLine(quot;Line {number} uses {card.Name}, which is retired: use {card.Instead} instead");
    }
}

record Card(string Name, string Status, string Marker, string Instead);
Row Importer: current
Ask GymManager: retired, use BookingService instead
Waitlist Reminder: proposed
Line 2 uses Ask GymManager, which is retired: use BookingService instead
// The team's catalog: each card's name, its status, the text that shows it's being used, and what replaces it.
record Card(String name, String status, String marker, String instead) {}

void main() {
    List<Card> catalog = List.of(
        new Card("Row Importer", "current", "importRows(", ""),
        new Card("Ask GymManager", "retired", "GymManager.", "BookingService"),
        new Card("Waitlist Reminder", "proposed", "", ""));

    for (Card card : catalog) {
        IO.println(card.status().equals("retired") ? card.name() + ": retired, use " + card.instead() + " instead" : card.name() + ": " + card.status());
    }

    // A teammate's new code, checked before it's merged.
    List<String> newCode = List.of(
        "Member maya = members.find(\"Maya\");",
        "int price = GymManager.priceOf(maya);",
        "List<Member> rows = importRows(text, this::makeMember);");
    for (int number = 1; number <= newCode.size(); number++) {
        for (Card card : catalog) {
            if (card.status().equals("retired") && newCode.get(number - 1).contains(card.marker())) {
                IO.println("Line " + number + " uses " + card.name() + ", which is retired: use " + card.instead() + " instead");
            }
        }
    }
}
Row Importer: current
Ask GymManager: retired, use BookingService instead
Waitlist Reminder: proposed
Line 2 uses Ask GymManager, which is retired: use BookingService instead
# The team's catalog: each card's name, its status, the text that shows it's being used, and what replaces it.
catalog = [
    {"name": "Row Importer", "status": "current", "marker": "import_rows(", "instead": ""},
    {"name": "Ask GymManager", "status": "retired", "marker": "GymManager.", "instead": "BookingService"},
    {"name": "Waitlist Reminder", "status": "proposed", "marker": "", "instead": ""},
]

for card in catalog:
    if card["status"] == "retired":
        print(f"{card['name']}: retired, use {card['instead']} instead")
    else:
        print(f"{card['name']}: {card['status']}")

# A teammate's new code, checked before it's merged.
new_code = [
    'maya = members.find("Maya")',
    "price = GymManager.price_of(maya)",
    "rows = import_rows(text, make_member)",
]
for number, line in enumerate(new_code, start=1):
    for card in catalog:
        if card["status"] == "retired" and card["marker"] in line:
            print(f"Line {number} uses {card['name']}, which is retired: use {card['instead']} instead")
Row Importer: current
Ask GymManager: retired, use BookingService instead
Waitlist Reminder: proposed
Line 2 uses Ask GymManager, which is retired: use BookingService instead
// The team's catalog: each card's name, its status, the text that shows it's being used, and what replaces it.
const catalog = [
  { name: "Row Importer", status: "current", marker: "importRows(", instead: "" },
  { name: "Ask GymManager", status: "retired", marker: "GymManager.", instead: "BookingService" },
  { name: "Waitlist Reminder", status: "proposed", marker: "", instead: "" },
];

for (const card of catalog) {
  console.log(card.status === "retired" ? `${card.name}: retired, use ${card.instead} instead` : `${card.name}: ${card.status}`);
}

// A teammate's new code, checked before it's merged.
const newCode = [
  'const maya = members.find("Maya");',
  "const price = GymManager.priceOf(maya);",
  "const rows = importRows(text, makeMember);",
];
newCode.forEach((line, index) => {
  for (const card of catalog) {
    if (card.status === "retired" && line.includes(card.marker)) {
      console.log(`Line ${index + 1} uses ${card.name}, which is retired: use ${card.instead} instead`);
    }
  }
});
Row Importer: current
Ask GymManager: retired, use BookingService instead
Waitlist Reminder: proposed
Line 2 uses Ask GymManager, which is retired: use BookingService instead
// The team's catalog: each card's name, its status, the text that shows it's being used, and what replaces it.
interface Card {
  name: string;
  status: "proposed" | "current" | "retired";
  marker: string;
  instead: string;
}

const catalog: Card[] = [
  { name: "Row Importer", status: "current", marker: "importRows(", instead: "" },
  { name: "Ask GymManager", status: "retired", marker: "GymManager.", instead: "BookingService" },
  { name: "Waitlist Reminder", status: "proposed", marker: "", instead: "" },
];

for (const card of catalog) {
  console.log(card.status === "retired" ? `${card.name}: retired, use ${card.instead} instead` : `${card.name}: ${card.status}`);
}

// A teammate's new code, checked before it's merged.
const newCode: string[] = [
  'const maya = members.find("Maya");',
  "const price = GymManager.priceOf(maya);",
  "const rows = importRows(text, makeMember);",
];
newCode.forEach((line, index) => {
  for (const card of catalog) {
    if (card.status === "retired" && line.includes(card.marker)) {
      console.log(`Line ${index + 1} uses ${card.name}, which is retired: use ${card.instead} instead`);
    }
  }
});
Row Importer: current
Ask GymManager: retired, use BookingService instead
Waitlist Reminder: proposed
Line 2 uses Ask GymManager, which is retired: use BookingService instead

Real tools do this for you: ESLint's no-restricted-imports and no-restricted-syntax rules in JavaScript and TypeScript, .NET's BannedApiAnalyzers for C#, ArchUnit tests for Java, and the flake8-tidy-imports plugin's banned modules for Python. Retiring a pattern often goes with replacing old code piece by piece, as in Strangler Fig: Replace an Old System One Piece at a Time.

When not to use it

  • For a small team with a few cards. Two people and three cards need a section in the README, not statuses and decision records.
  • When it turns into paperwork. If changing a card needs a meeting, nobody will change cards, and the catalog drifts the same way the wiki did. A card change should be as easy as a code change.
  • For what the framework already documents. The catalog is for the team's own decisions.

Check yourself

2 questions to try on the lesson page.

So what

Patterns go out of date like code does. Keep the cards beside the code, give each one a status, write down why it changed, and when one retires, mark it, point to what replaces it, and let a check catch new uses.

Key terms

Cheat sheets