Alternative Classes with Different Interfaces

Signs

• Two classes have methods that do the same thing under different names: sendSms(to, text) and deliver(message).
• Callers contain if (provider === "a") a.foo() else b.bar() to bridge the difference.
• The implementations duplicate logic such as retries, rate limiting or formatting.
• One class was written later by someone who did not know the other existed.

Why it happens

Two teams or two people solve the same problem at different times. A vendor switch or a second payment provider is added next to the first rather than behind a shared contract. Each class gets names that fit the vendor's own API, so the interfaces diverge even though the intent is identical.

Example

Two SMS providers integrated separately.

class TwilioClient {
  async sendSms(toNumber: string, body: string): Promise<string> { /* returns message SID */ return ""; }
}

class VonageClient {
  async deliver(msg: { recipient: string; text: string; from?: string }): Promise<{ id: string }> {
    return { id: "" };
  }
}

async function sendVerificationCode(phone: string, code: string, region: string) {
  const text = `Your code is ${code}`;
  if (region === "EU") {
    const res = await new VonageClient().deliver({ recipient: phone, text });
    return res.id;
  }
  return new TwilioClient().sendSms(phone, text);
}

One interface with matching signatures removes the branch from callers.

interface SmsSender {
  send(to: string, text: string): Promise<string>;
}

class TwilioSender implements SmsSender {
  async send(to: string, text: string): Promise<string> { /* ... */ return ""; }
}

class VonageSender implements SmsSender {
  async send(to: string, text: string): Promise<string> {
    const res = await vonage.deliver({ recipient: to, text });
    return res.id;
  }
}

async function sendVerificationCode(sender: SmsSender, phone: string, code: string) {
  return sender.send(phone, `Your code is ${code}`);
}

Treatment

• Start with Rename Method so methods that mean the same thing share a name.
• Align signatures with Add Parameter and Parameterize Method until the methods take and return the same shapes.
• If only part of a class matches the other, use Move Method to relocate behavior so the matching parts line up.
• Once the methods match, use Extract Interface so callers depend on the shared contract.
• If the implementations also share real code, use Extract Superclass to hold it. Prefer an interface plus a shared helper when the classes wrap different third-party SDKs.
• If one class is a strict subset of the other, delete it and redirect its callers.

Payoff

• Callers can swap implementations without branching, which makes tests with fakes straightforward.
• Duplicate logic around the call (retry, logging) collapses into one place.
• Adding a third provider means one new class, not another branch in each caller.

When to ignore

• The classes look alike but serve different domains that will diverge, such as transactional email and marketing email with different compliance rules.
• The classes live in separate libraries you do not control. Wrap them with an Adapter in your code instead of trying to change them.
• Only one caller uses both, and it is about to be deleted.

Agent checklist

• You confirmed the two classes have the same intent and the same failure semantics, not only similar names.
• Renames are applied across every caller, including dynamic lookups and string references.
• The extracted interface contains only methods every implementation supports fully.
• Callers receive the interface through a parameter or constructor rather than constructing a concrete class.
• Each implementation passes the same contract test suite.