Seam Type Selector

Select the right seam type (Preprocessor / Link / Object) for breaking a dependency in legacy code. Use whenever a developer needs to substitute behavior for...

When to Use

Use this skill when a developer needs to substitute or intercept behavior in legacy code for testing, but cannot freely edit the code under test. Specifically:

• The code has a hard-coded dependency (global function, library call, concrete class instantiation) that prevents running it in a test harness.
• The developer asks: "How do I fake this?", "How do I test around this global?", "How do I intercept this call without a DI framework?", or "What's the right way to introduce a test double here?"
• The developer is choosing between approaches (subclass override vs. classpath swap vs. macro replacement) and needs a principled recommendation.

Do not use for greenfield code where a dependency injection framework is already in place — the framework already manages enabling points.

---

Context and Input Gathering

Before recommending a seam type, gather:

1. Language — Is this C or C++ (preprocessor available)? A compiled OO language like Java or C# (link and object seams)? A dynamic OO language like Python or Ruby (object seams, plus text redefinition)?
2. Dependency type — What exactly needs to be substituted? Options: global function, static method, constructor call, third-party library, concrete class member.
3. Pervasiveness — Is this dependency called in one or two places, or scattered across dozens of files and hundreds of call sites?
4. Risk tolerance — Is modifying production class structure (adding a virtual method, adding a constructor parameter) acceptable? Some teams forbid structural changes to classes under test without prior test coverage.

---

Process

Step 1: Confirm a seam exists

A seam (Feathers' formal definition) is "a place where you can alter behavior in your program without editing in that place." Verify the target call site qualifies:

• You want to substitute the behavior that runs at call site X.
• You can make the substitution without modifying the source text at X itself.
• There is an enabling point — a separate place where you decide which behavior to use.

If no enabling point can be identified, there is no seam. You will need to introduce one first (see dependency-breaking-technique-executor).

Step 2: Classify the dependency

Classification	Characteristic	Examples
Localized	1–5 call sites, within one class or module	One new DatabaseConnection() in a constructor
Pervasive	Many call sites, spread across files	50+ calls to getenv() throughout a C codebase; all files import a logging singleton

Pervasiveness is the primary override condition. If a dependency is pervasive, the cost of introducing object seams at every site may exceed the cost of a single link- or preprocessor-level substitution.

Step 3: Assess language capabilities

Language	Preprocessor Seam	Link Seam	Object Seam
C	Yes (#define, #ifdef)	Yes (object file swap)	No (procedural)
C++	Yes	Yes	Yes
Java, Kotlin	No	Yes (classpath)	Yes
C#	No	Yes (assembly)	Yes
Python, Ruby	No	Limited	Yes (duck typing)
Go	No	Limited	Yes (interfaces)
TypeScript/JS	No	Limited (module mock)	Yes

Step 4: Apply the selection rule

Feathers states: "In general, object seams are the best choice in object-oriented languages. Preprocessing seams and link seams can be useful at times but they are not as explicit as object seams. Tests that depend on them can be hard to maintain. Reserve preprocessing seams and link seams for cases where dependencies are pervasive and there are no better alternatives."

Decision hierarchy:

1. Is the language OO and the dependency localized?
   → Use Object Seam

2. Is the language OO but the dependency is pervasive (many call sites)?
   → Prefer Link Seam (keeps source changes minimal)
   → Fall back to Preprocessor Seam only in C/C++

3. Is the language procedural C/C++ and the dependency is pervasive?
   → Link Seam first; Preprocessor Seam if link is not feasible

4. Is the language procedural C/C++ and the dependency is localized?
   → Preprocessor Seam (only option available)

Step 5: Identify the enabling point

Every seam has an enabling point — name it explicitly. Future readers (and the developer implementing the seam) must know where to flip the switch.

Seam Type	Where the Enabling Point Lives
Object Seam	Where the object is constructed or injected — a constructor, factory method, parameter, or setter
Link Seam	The build configuration — classpath entry, Makefile rule, linker flag, or IDE project setting
Preprocessor Seam	A preprocessor define — #define TESTING, a -DTESTING compiler flag, or an #include of a test-override header

Step 6: Produce the recommendation artifact

Output a seam-recommendation.md (template in Outputs section) with: seam type, enabling point location, rationale, language note, and a list of compatible Part III techniques the developer can apply next.

---

Inputs

Input	Required	Description
Source file(s)	Required	The file(s) containing the dependency to break
Language	Required	Programming language of the codebase
Dependency description	Required	What call/class/library needs to be substituted
Pervasiveness assessment	Recommended	Number of call sites; single file vs. codebase-wide
Risk constraints	Optional	Whether structural changes to production classes are allowed

---

Outputs

seam-recommendation.md

## Seam Recommendation: [dependency name]

**Chosen Seam Type:** [Object / Link / Preprocessor]

**Enabling Point:**
[Exact location — e.g., "The constructor of OrderProcessor (line 42 of OrderProcessor.java)"
or "The classpath entry resolving com.example.PaymentGateway"
or "The TESTING preprocessor define passed via -DTESTING in the Makefile"]

**Rationale:**
[1–3 sentences: why this seam type for this language, dependency type, and pervasiveness level]

**Language Applicability:**
[Confirm the seam is available in the target language; note if a fallback was chosen]

**Compatible Part III Techniques:**
- [Technique name] — [one-line explanation of how it exploits this seam]
- [Technique name] — ...

**Next step:** See `dependency-breaking-technique-executor` to apply the selected technique.

---

Key Principles

1. Prefer object seams for maintainability. Object seams are explicit — the substitution is visible in the source code at the enabling point. Link and preprocessor seams substitute behavior invisibly; future readers see nothing unusual at the call site.

2. Every seam has an enabling point — name it explicitly. A seam without a named enabling point is incomplete. The enabling point is where the developer acts; without naming it, the recommendation cannot be implemented.

3. Pervasive dependencies may justify link or preprocessor seams. When a global function is called in 80 places across 20 files, introducing a virtual dispatch at each site is high-risk surgery. A single build-level substitution is safer than 80 structural edits.

4. Seams make the substitution point visible to future readers. The goal is not just to make tests pass today — it is to leave the codebase in a state where the next engineer can understand which behavior is being substituted and why.

---

Examples

Example A: Java class with a hard-coded dependency (Object Seam)

Situation: A UserService class has a constructor that directly instantiates UserRepository, which opens a database connection. No DI framework. Need to test UserService.findActiveUsers() without a real database.

Classification: Localized (one constructor site). Language: Java (OO).

Recommendation: Object Seam.

Enabling point: The UserService constructor. Introduce a second constructor that accepts a UserRepository parameter (Parameterize Constructor technique). Tests pass in a fake implementation; production code calls the original constructor.

Compatible techniques: Parameterize Constructor, Extract Interface (extract IUserRepository), Subclass and Override Method.

---

Example B: C++ with pervasive global calls (Link Seam)

Situation: A legacy C++ codebase has 60+ calls to log_event() (a global that writes to a syslog daemon) scattered across 15 files. Running tests triggers syslog writes and slows everything down.

Classification: Pervasive. Language: C++ (compiled, OO).

Recommendation: Link Seam.

Enabling point: The Makefile's link step. Create a test_log_event.o object file with a stub log_event() that records calls in memory. Swap it in via the Makefile for test builds. Source files are untouched.

Compatible techniques: Link-level substitution (Ch 19 procedural pattern), Encapsulate Global References (if later migration to OO is planned).

---

Example C: Legacy C with pervasive global calls (Preprocessor Seam)

Situation: A C codebase calls db_update(account_no, record) in 40 places across 8 files. There is no OO structure and no link-time substitution capability in the build environment.

Classification: Pervasive. Language: C (procedural — no object seam available).

Recommendation: Preprocessor Seam.

Enabling point: A #define TESTING flag passed to the C compiler (e.g., gcc -DTESTING). A localdefs.h header, included in each source file, defines a macro replacement for db_update under #ifdef TESTING that captures arguments without hitting the database.

Compatible techniques: Text Redefinition (C/C++ specific), C macro preprocessor pattern (Ch 19).

---

References

See references/seam-type-comparison.md for a full comparison matrix of all three seam types across language families, enabling point locations, and compatible Chapter 25 techniques.

---

License

CC-BY-SA-4.0 — derived from Working Effectively with Legacy Code by Michael C. Feathers (2004).

---

Related BookForge Skills

• dependency-breaking-technique-executor — Takes a seam recommendation and applies a specific Chapter 25 technique step-by-step. This skill feeds directly into it.
• legacy-code-change-algorithm — The outer 6-step procedure. Seam identification is Step 3 of that algorithm; use this skill to complete it.
• library-seam-wrapper — Applies the link seam pattern specifically to third-party library dependencies, wrapping them in an interface.