# Writing a Pattern Card Your Team Will Read

A shared solution that nobody knows about, or knows when to use, gets copied around anyway; a pattern card says on one page what problem it solves, how to use it, when to skip it and where it's already used, so a teammate can pick it up without asking.

Journeyman · Software Development · OOP · Updated November 17, 2026

By Gregor Dzierzon

## After this lesson you can

- Write a pattern card for a team's repeated solution, with its problem, idea, example, use it when and skip it when
- Judge a pattern card by whether a teammate could tell from it alone when to use the pattern and when not to

## Key takeaways

- Code shows how a solution works. It can't say that it exists, when to use it, when not to, or who to ask.
- A pattern card uses the same fields as this course's cards: name, problem, smells, idea, example, use it when, skip it when, look-alikes.
- A team's card adds where the pattern is already used and who owns it, so it stays tied to real code.
- A good card fits on one page, states the problem before the solution, and is as clear about when to skip it as when to use it.

**Before this:** *When Repetition Becomes a Pattern: The Rule of Three*, which pulls out the row importer this lesson writes up.

Two months after Summit Gym's teams pulled out the row importer, Dana joins the team and is asked to load the waitlist spreadsheet. She finds the newest importer in the code, the class-times one from before the change, copies it, and changes the last line. Her copy forgets the blank-line check, and a blank line at the end of the waitlist file breaks the first import. Nobody told Dana that `importRows` exists. Even if she'd found it, nothing in the function says which spreadsheets it's for, or where it goes wrong. By the end of this lesson you'll be able to write the one page that would have saved her afternoon: a *pattern card*.

## What code can't tell a teammate

`importRows` is twelve good lines, with a comment that says what they do. What the code can't say:

- **that it exists**, to someone who doesn't know where to look;
- **which problem it's for**, so someone with that problem finds it;
- **when not to use it**: this one splits at every comma, so a spreadsheet cell holding "studio A, upstairs" would be cut in two;
- **where it's already used**, as examples to copy;
- **who to ask** when it doesn't fit.

## What would you try?

**A longer comment above the function.** It helps whoever opens that file. Dana never opened it.

**A message in the team chat.** Read once, and scrolled out of sight within a week.

**A wiki page with everything about importing.** Three pages nobody reads before loading one spreadsheet.

What we want: one short page, in a shape the team recognizes, that someone with the problem can find and read in two minutes.

## The card's shape

This course's own pattern card works for any pattern, including one nobody outside your team has heard of. A team's card adds two fields: where the pattern is already used, and who owns it. Here is the Row Importer's:

| Field | The Row Importer |
|---|---|
| Name | Row Importer |
| The problem | Every team that loads a spreadsheet writes the same reading, skipping and splitting code again, and each copy handles mistakes its own way. |
| Smells that point here | A loop over a file's lines that skips the first one; the same split-at-commas-and-trim code in more than one importer |
| The idea | One function does the shared steps (skip the header and blank lines, split each line, trim each value); you hand it a function that turns one row into what you need. |
| Example | The equipment importer |
| Use it when | A simple spreadsheet export: one row per line, values separated by commas, a header line first |
| Skip it when | A value can hold a comma or quotes, such as "studio A, upstairs": use your language's CSV reader instead. Or the data isn't a spreadsheet, such as JSON from a web service. |
| Where it's used | The members, instructors and class-times importers |
| Look-alikes | Template Method (the same steps, with your own step); your language's CSV reader, for files this one can't read |
| Owner | The front-desk team |

The *Example* field is the smallest real use, the equipment team's importer:

```csharp
// The card's example: the smallest use of the Row Importer, for a new spreadsheet.
string equipmentFile = "item,room\nmats,studio A\n\nbikes, studio B";
Console.WriteLine("Equipment: " + string.Join(", ", ImportRows(equipmentFile, row => $"{row[0]} in {row[1]}")));

List<T> ImportRows<T>(string text, Func<string[], T> makeRow)
{
    List<T> rows = new List<T>();
    foreach (string line in text.Trim().Split('\n').Skip(1))
    {
        if (line.Trim() == "") { continue; }
        rows.Add(makeRow(line.Split(',').Select(value => value.Trim()).ToArray()));
    }
    return rows;
}
```

```text
Equipment: mats in studio A, bikes in studio B
```

```java
<T> List<T> importRows(String text, Function<String[], T> makeRow) {
    List<T> rows = new ArrayList<>();
    for (String line : text.strip().lines().skip(1).toList()) {
        if (line.isBlank()) { continue; }
        String[] values = Arrays.stream(line.split(",")).map(String::strip).toArray(String[]::new);
        rows.add(makeRow.apply(values));
    }
    return rows;
}

void main() {
    // The card's example: the smallest use of the Row Importer, for a new spreadsheet.
    String equipmentFile = "item,room\nmats,studio A\n\nbikes, studio B";
    IO.println("Equipment: " + String.join(", ", importRows(equipmentFile, row -> row[0] + " in " + row[1])));
}
```

```text
Equipment: mats in studio A, bikes in studio B
```

```python
def import_rows(text, make_row):
    rows = []
    for line in text.strip().split("\n")[1:]:
        if line.strip() == "":
            continue
        rows.append(make_row([value.strip() for value in line.split(",")]))
    return rows


# The card's example: the smallest use of the Row Importer, for a new spreadsheet.
equipment_file = "item,room\nmats,studio A\n\nbikes, studio B"
print("Equipment: " + ", ".join(import_rows(equipment_file, lambda row: f"{row[0]} in {row[1]}")))
```

```text
Equipment: mats in studio A, bikes in studio B
```

```javascript
function importRows(text, makeRow) {
  const rows = [];
  for (const line of text.trim().split("\n").slice(1)) {
    if (line.trim() === "") { continue; }
    rows.push(makeRow(line.split(",").map((value) => value.trim())));
  }
  return rows;
}

// The card's example: the smallest use of the Row Importer, for a new spreadsheet.
const equipmentFile = "item,room\nmats,studio A\n\nbikes, studio B";
console.log("Equipment: " + importRows(equipmentFile, (row) => `${row[0]} in ${row[1]}`).join(", "));
```

```text
Equipment: mats in studio A, bikes in studio B
```

```typescript
function importRows<T>(text: string, makeRow: (row: string[]) => T): T[] {
  const rows: T[] = [];
  for (const line of text.trim().split("\n").slice(1)) {
    if (line.trim() === "") { continue; }
    rows.push(makeRow(line.split(",").map((value) => value.trim())));
  }
  return rows;
}

// The card's example: the smallest use of the Row Importer, for a new spreadsheet.
const equipmentFile = "item,room\nmats,studio A\n\nbikes, studio B";
console.log("Equipment: " + importRows(equipmentFile, (row) => `${row[0]} in ${row[1]}`).join(", "));
```

```text
Equipment: mats in studio A, bikes in studio B
```

![The Row Importer's pattern card, one row per field filled in: the problem, smells that point here, the idea, an example, use it when, skip it when (flagged in orange), where it's used, look-alikes and its owner](https://fsdtrainingmedia.blob.core.windows.net/public/images/2026/11/d33077916109494aa527cff4e1c4ec01.webp)

## Writing each field well

- **Name it for what it does,** in words a teammate can say out loud in a review: "use the Row Importer". Not "CsvUtil2", and not "the Strategy-based importer": the name should say the problem's area, not the machinery.
- **The problem comes first,** in one sentence, from the reader's side: what they're trying to do and what goes wrong. If you can't write the problem, you don't have a pattern yet.
- **"Skip it when" matters as much as "use it when".** The quoted comma is exactly where this pattern breaks, and saying so saves the next person a bad afternoon. Every pattern has a cost or a limit; a card that lists none is hiding one.
- **"Where it's used" is the proof.** Three real places, by name, show it's a pattern and not an idea, and give a newcomer working examples.
- **One page.** Link to the code for the details. A card is read when someone is in the middle of a task.

## What would have changed for Dana

With the card in the team's catalog, Dana searches for "spreadsheet", finds the Row Importer, and writes her waitlist importer in one line, with the blank lines handled for her. And when she sees that the waitlist file has a column like "Maya, Sam" in one cell, the card's *Skip it when* tells her to use the CSV reader for that one, before it breaks anything.

## When not to write one

- **For a solution used once or twice.** Wait for the third use (the rule of three).
- **For something your language or framework already documents.** Nobody needs a card that says "use the built-in sort".
- **For a helper with no decision in it.** A card earns its place when there's a *when* and a *when not*: a choice a teammate could get wrong.

## Check yourself

2 questions to try on the lesson page.

## So what

Code says how a solution works; a card says when to use it, when not to, and where it already lives. One page in a shape the team knows turns a helper one person wrote into a pattern the whole team uses.

## Key terms

- [Design Pattern](https://www.ask-codey.com/glossary/design-pattern)
- [Code Smell](https://www.ask-codey.com/glossary/code-smell)
- [Trade-Off](https://www.ask-codey.com/glossary/trade-off)

## Cheat sheets

- [Writing a Pattern Card Your Team Will Read](https://www.ask-codey.com/cheat-sheets/dp-writing-a-pattern-card-cheat-sheet)

Source: https://www.ask-codey.com/lessons/dp-writing-a-pattern-card
