System Design (LLD)Method Signature Design

Method Signature Design

LevelIntermediate

Duration60 mins

TopicMethod Signature Design

4 / 4

Overloading Guidelines

Overloading: Power and Peril

Method overloading—defining multiple methods with the same name but different parameter lists—is a double-edged sword. Used well, it creates intuitive, flexible APIs where the right method is called based on the caller's context. Used poorly, it creates confusion, subtle bugs, and maintenance nightmares.

Consider this overloaded API:

// Which method does this call?
logger.log(null);

Is null a String message? An Exception? An Object with context? The compiler must choose, and its choice might not match the developer's intent. Worse, changing which overload is selected can happen silently when code is refactored.

Overloading is powerful, but it demands discipline. This page teaches you when to use it, when to avoid it, and how to apply it safely.

What You Will Master

By the end of this page, you will understand overloading's mechanics, recognize dangerous overloading patterns, and apply guidelines that keep overloading safe and intuitive. You'll also learn alternatives for languages that don't support overloading natively.

How Overloading Works

Overloading allows a class to have multiple methods with the same name, distinguished by their parameter lists. The compiler or runtime selects which overload to invoke based on the arguments provided.

Compile-Time (Static) Resolution

In most statically-typed languages (Java, C#, C++, TypeScript), overload resolution happens at compile time. The compiler examines the declared types of arguments and selects the most specific matching overload.

public class Logger {
    public void log(String message) {
        System.out.println("String: " + message);
    }
    
    public void log(Object obj) {
        System.out.println("Object: " + obj);
    }
    
    public void log(Exception e) {
        System.out.println("Exception: " + e.getMessage());
    }
}

Logger logger = new Logger();
logger.log("hello");        // Calls log(String) — exact match
logger.log(new Exception()); // Calls log(Exception) — exact match
logger.log(new Object());    // Calls log(Object) — exact match
logger.log(42);              // Calls log(Object) — Integer autoboxed to Object

Key Insight: Static Types Matter

The declared type of the argument determines which overload is selected, not the runtime type:

Object message = "hello"; // Declared type is Object
logger.log(message);      // Calls log(Object), NOT log(String)!

// Even though the runtime type is String, the compile-time type is Object

This distinction causes subtle bugs when developers expect runtime polymorphism.

Static Resolution Surprise

Overloading is resolved statically; overriding is resolved dynamically. This asymmetry catches many developers off guard. If you pass a String through an Object variable, the compiler sees Object and selects accordingly.

When Overloading Helps

Despite its pitfalls, overloading genuinely improves API usability in several scenarios.

1. Progressive Parameter Lists

Overloading shines when providing convenience methods that build on a fully-specified version:

progressive-overloads.java
Java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
public class HttpClient {
    // Full version with all options
    public HttpResponse send(HttpRequest request, HttpOptions options) {
        // Implementation with full control
    }
    
    // Convenience overload with default options
    public HttpResponse send(HttpRequest request) {
        return send(request, HttpOptions.defaults());
    }
}
 
public class StringBuilder {
    // Full version
    public StringBuilder append(CharSequence s, int start, int end) {
        // Implementation
    }
    
    // Convenience: append entire sequence
    public StringBuilder append(CharSequence s) {
        return append(s, 0, s.length());
    }
    
    // Convenience: append single char
    public StringBuilder append(char c) {
        return append(String.valueOf(c));
    }
}

2. Type-Specific Optimizations

Overloading allows optimized implementations for specific types while maintaining a general-purpose version:

public class Arrays {
    // General version using Object comparison
    public static <T> int indexOf(T[] array, T element) {
        for (int i = 0; i < array.length; i++) {
            if (Objects.equals(array[i], element)) return i;
        }
        return -1;
    }
    
    // Optimized version for primitives (avoids boxing)
    public static int indexOf(int[] array, int element) {
        for (int i = 0; i < array.length; i++) {
            if (array[i] == element) return i;
        }
        return -1;
    }
    
    // Similar overloads for long[], double[], etc.
}

3. Alternative Input Formats

When the same operation can accept data in different formats:

public class DateParser {
    public LocalDate parse(String dateString) {
        return LocalDate.parse(dateString);
    }
    
    public LocalDate parse(long epochMillis) {
        return Instant.ofEpochMilli(epochMillis)
            .atZone(ZoneId.systemDefault())
            .toLocalDate();
    }
    
    public LocalDate parse(int year, int month, int day) {
        return LocalDate.of(year, month, day);
    }
}

Good Overloading Characteristics

•Same semantic operation — All overloads do fundamentally the same thing
•Different input representations — Each overload accepts a different valid form of input
•Clear type distinctions — Parameter types are obviously different (String vs int, not List<String> vs List<Integer>)
•Delegation pattern — Simpler overloads delegate to fuller versions
•No behavioral surprises — Calling any overload produces predictable results

When Overloading Hurts

Overloading becomes dangerous when it introduces ambiguity, causes unexpected method selection, or creates brittle APIs.

1. Overloading with Related Types

Overloading methods where parameter types are related through inheritance causes resolution surprises:

related-types-problem.java
Java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
public class Printer {
    public void print(Collection<?> collection) {
        System.out.println("Collection: " + collection);
    }
    
    public void print(List<?> list) {
        System.out.println("List: " + list);
    }
    
    public void print(Set<?> set) {
        System.out.println("Set: " + set);
    }
}
 
// Problem: Which gets called?
Printer printer = new Printer();
Collection<?> items = new ArrayList<>(); // Declared as Collection
printer.print(items); // Calls print(Collection), not print(List)!
 
// The runtime type is ArrayList (a List), but the compile-time 
// type is Collection, so print(Collection) is selected.

2. Overloading with Autoboxing/Unboxing

Autoboxing in Java creates particularly insidious overloading problems:

autoboxing-problem.java
Java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
public class ListUtils {
    public static void remove(List<Integer> list, int index) {
        list.remove(index); // Removes element at index
    }
    
    public static void remove(List<Integer> list, Integer value) {
        list.remove(value); // Removes element by value
    }
}
 
List<Integer> numbers = new ArrayList<>(List.of(1, 2, 3));
 
// Which overload is called?
ListUtils.remove(numbers, 1); // Calls remove(list, int) — removes index 1
 
// To remove value 1, you need explicit boxing:
ListUtils.remove(numbers, Integer.valueOf(1)); // Removes value 1
 
// This is confusing and error-prone!

3. Overloading with Varargs

Varargs combined with overloading creates resolution nightmares:

varargs-problem.java
Java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
public class Logger {
    public void log(String message) {
        log(message, new Object[0]);
    }
    
    public void log(String message, Object... args) {
        System.out.printf(message, args);
    }
}
 
Logger logger = new Logger();
logger.log("Hello");           // Which one? Ambiguous in some cases!
logger.log("Hello", null);     // Is null the varargs array or an argument?
 
// Even worse with multiple varargs-like methods:
public void log(String... messages);     // Log multiple messages
public void log(String message, Object... args); // Format message
 
logger.log("a", "b"); // Compile error: ambiguous!

Dangerous Overloading Patterns

•Related types — Overloading with Collection/List/Set, Object/String, Number/Integer
•Primitive/Wrapper pairs — int/Integer, long/Long creates autoboxing confusion
•Multiple varargs — More than one varargs overload almost always causes problems
•Functional interfaces with same arity — Runnable vs Supplier, Consumer vs Function
•Null ambiguity — When null could match multiple overloads
•Generics with erasure — List<String> and List<Integer> are same at runtime

The Generics Erasure Trap

In Java, void process(List<String> strings) and void process(List<Integer> integers) cannot coexist as overloads—they have the same erasure. The compiler sees both as void process(List list) and rejects the second definition.

Overloading Resolution Rules

Understanding how compilers resolve overloads helps you predict and avoid problems.

Java Overload Resolution Algorithm

Java's resolution follows a multi-phase process:

Find applicable methods — Methods where arguments can be converted to parameter types
Among applicable methods, find most specific — The overload whose parameters are subtypes of all others
If no single most specific exists — Compile error (ambiguous)

Phase Details:

resolution-phases.java
Java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
public class Resolver {
    public void process(Object o) { }      // A
    public void process(String s) { }      // B
    public void process(Integer i) { }     // C
}
 
Resolver r = new Resolver();
 
// Call 1: process("hello")
// Applicable: A (String → Object), B (String → String exact)
// Most specific: B (String is more specific than Object)
r.process("hello"); // Calls B
 
// Call 2: process(42)
// Applicable: A (Integer → Object), C (int → Integer after boxing)
// Most specific: C (Integer more specific than Object)
r.process(42); // Calls C
 
// Call 3: process(new Object())
// Applicable: A only (Object → Object)
r.process(new Object()); // Calls A
 
// Call 4: What about...
Number num = 42;
// Applicable: A (Number → Object)
// C is NOT applicable: Number is not Integer
r.process(num); // Calls A, even though runtime type is Integer!

TypeScript Overload Resolution

TypeScript uses a different approach—overload signatures are tried in declaration order:

// TypeScript: order matters!
function format(value: string): string;
function format(value: number): string;
function format(value: Date): string;
function format(value: string | number | Date): string {
    if (typeof value === 'string') return value;
    if (typeof value === 'number') return value.toString();
    return value.toISOString();
}

// First matching signature wins
format("hello"); // Matches first overload
format(42);      // Matches second overload
format(new Date()); // Matches third overload

Test Overload Resolution

When creating overloaded methods, write explicit tests that verify the correct overload is selected for edge cases—especially for null, boxed primitives, and subtype arguments. Don't assume; verify.

Guidelines for Safe Overloading

Apply these guidelines to keep overloading safe and intuitive:

Safe Overloading Guidelines

•Radically different parameter types — Overloads should have parameter types that are obviously and completely different. String and InputStream are clearly different; Collection and List are dangerously similar.
•Same semantic behavior — All overloads must do the same thing conceptually. Don't use overloading to provide different behaviors—that's what different method names are for.
•Delegate to canonical implementation — Simpler overloads should call through to the most complete overload. This ensures consistent behavior and reduces bug surface.
•Avoid overloading with related types — If types are related by inheritance or interface, reconsider. Use different method names instead.
•Never overload on functional interfaces — process(Runnable r) vs process(Supplier<T> s) with lambdas is a recipe for confusion.
•Test null explicitly — If null is a valid argument, test which overload it selects. Consider whether null should be valid at all.
•Document intended overload — In complex cases, document which overload should be called for ambiguous scenarios.

unsafe-overloading.java
Java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// UNSAFE: Related types
void process(Object o);
void process(String s);
void process(CharSequence cs);
 
// UNSAFE: Functional interfaces
void execute(Runnable r);
void execute(Callable<T> c);
 
// UNSAFE: Primitive/wrapper
void set(int value);
void set(Integer value);
 
// UNSAFE: Generic erasure
void handle(List<String> strs);
void handle(List<Integer> ints);

safe-overloading.java
Java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// SAFE: Radically different types
void load(File file);
void load(URL url);
void load(InputStream stream);
 
// SAFE: Different arities
void connect();
void connect(Config config);
 
// SAFE: Primitives + objects distinct
void print(int number);
void print(String text);
 
// SAFE: Different method names
void handleStrings(List<String> s);
void handleIntegers(List<Integer> i);

The Effective Java Rule

Josh Bloch's "Effective Java" provides a memorable test: "A safe, conservative policy is never to export two overloadings with the same number of parameters." While strict, this heuristic prevents most overloading hazards.

Alternatives to Overloading

Many scenarios where developers reach for overloading are better served by alternatives.

1. Static Factory Methods with Descriptive Names

Instead of overloaded constructors or factory methods, use distinctly named static factories:

factory-methods.java
Java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
// Instead of overloaded constructors:
// new User(String name)
// new User(String email, boolean verified)
// new User(ExternalUser external)
 
// Use named factory methods:
public class User {
    private User() { }
    
    public static User withName(String name) {
        User u = new User();
        u.name = name;
        return u;
    }
    
    public static User fromEmail(String email, boolean verified) {
        User u = new User();
        u.email = email;
        u.verified = verified;
        return u;
    }
    
    public static User fromExternal(ExternalUser external) {
        User u = new User();
        u.externalId = external.getId();
        u.name = external.getDisplayName();
        return u;
    }
}
 
// Call sites are self-documenting:
User.withName("Alice");
User.fromEmail("alice@example.com", true);
User.fromExternal(externalUser);

2. Builder Pattern

For methods with many optional parameters, builders eliminate overloading entirely:

// Instead of:
sendEmail(to);
sendEmail(to, subject);
sendEmail(to, subject, body);
sendEmail(to, subject, body, attachments);
sendEmail(to, subject, body, attachments, options);

// Use a builder:
Email.to("user@example.com")
    .subject("Hello")
    .body("Content here")
    .attach(file1, file2)
    .withOption(EmailOption.TRACK_OPENS)
    .send();

3. Parameter Objects

Consolidate related parameters into an object:

// Instead of:
void search(String query);
void search(String query, int limit);
void search(String query, int limit, int offset);
void search(String query, int limit, int offset, SortOrder sort);

// Use a request object:
Record SearchRequest(String query, int limit, int offset, SortOrder sort) {
    // Provide defaults via factory methods
    public static SearchRequest of(String query) {
        return new SearchRequest(query, 10, 0, SortOrder.RELEVANCE);
    }
}

void search(SearchRequest request);

4. Method Name Variants

For semantically different operations, just use different names:

// Instead of ambiguous overloads:
void log(String message);
void log(Exception e);
void log(String message, Exception e);

// Use clear names:
void logMessage(String message);
void logException(Exception e);
void logError(String message, Exception cause);

Python's Approach

Python intentionally lacks method overloading. Instead, it uses default arguments, *args/**kwargs, and explicit type checking within the method. While less type-safe, this avoids all overloading complexity: def process(data, format='json', **options):.

Language-Specific Considerations

Different languages handle overloading differently. Understanding these differences is crucial when designing cross-language APIs or working in polyglot environments.

Java Overloading

Full overloading support with compile-time resolution
Autoboxing creates int/Integer ambiguity
Generic type erasure prevents List<A>/List<B> overloads
Varargs complicates resolution
Return type alone cannot distinguish overloads

// Valid overloads
void process(String s);
void process(int i);
void process(String s, int i);

// Invalid: return type only
// String getValue();
// int getValue(); // ERROR: duplicate method

// Invalid: erasure
// void handle(List<String> s);
// void handle(List<Integer> i); // ERROR: same erasure

Java Best Practice: Use overloading sparingly. Prefer named factory methods, builders, or distinct method names when there's any ambiguity risk.

Summary: Overloading with Discipline

Method overloading is a powerful tool for creating flexible APIs, but it demands respect and discipline. Misused overloading creates subtle bugs and confusing APIs. Applied carefully, it provides convenience without confusion.

Key Takeaways

•Overloading is static — The compile-time type determines which overload is called, not the runtime type. This surprises many developers.
•Use radically different types — Overload only when parameter types are obviously and completely different. String vs. File: good. List vs. Collection: dangerous.
•Same semantics required — All overloads must do the same conceptual operation. Different behaviors need different method names.
•Delegate to canonical version — Simpler overloads should call through to the most complete version, ensuring consistent behavior.
•Avoid related types — Inheritance hierarchies, boxing pairs, and generic erasure all create hazards. When in doubt, use distinct names.
•Consider alternatives — Named factory methods, builders, and parameter objects often work better than overloading.
•Know your language — Overloading rules vary. Java erases generics. TypeScript uses signature ordering. Python and Go don't support overloading.
•Test edge cases — Explicitly test null handling, boxing, and subtype arguments to verify correct overload selection.

Module Complete

You've now mastered all four pillars of method signature design:

Method Naming — Revealing intent through precise, consistent vocabulary
Parameter Design — Creating intuitive, type-safe, hard-to-misuse parameters
Return Types — Communicating results and handling all outcomes gracefully
Overloading — Using power wisely to create flexible yet predictable APIs

Together, these skills enable you to design method signatures that make APIs intuitive, safe, and a pleasure to use.

Module Complete

You've completed Module 2: Method Signature Design. You now have the knowledge to design method signatures like a Principal Engineer—signatures that are intuitive, type-safe, consistent, and robust. Apply these principles consistently, and your APIs will earn the trust and appreciation of every developer who uses them.

4 / 4

Loading learning content...

System Design (LLD)Method Signature Design

Method Signature Design

LevelIntermediate

Duration60 mins

TopicMethod Signature Design

4 / 4

Overloading Guidelines

Overloading: Power and Peril

Consider this overloaded API:

// Which method does this call?
logger.log(null);

Overloading is powerful, but it demands discipline. This page teaches you when to use it, when to avoid it, and how to apply it safely.

What You Will Master

How Overloading Works

Compile-Time (Static) Resolution

public class Logger {
    public void log(String message) {
        System.out.println("String: " + message);
    }
    
    public void log(Object obj) {
        System.out.println("Object: " + obj);
    }
    
    public void log(Exception e) {
        System.out.println("Exception: " + e.getMessage());
    }
}

Logger logger = new Logger();
logger.log("hello");        // Calls log(String) — exact match
logger.log(new Exception()); // Calls log(Exception) — exact match
logger.log(new Object());    // Calls log(Object) — exact match
logger.log(42);              // Calls log(Object) — Integer autoboxed to Object

Key Insight: Static Types Matter

The declared type of the argument determines which overload is selected, not the runtime type:

Object message = "hello"; // Declared type is Object
logger.log(message);      // Calls log(Object), NOT log(String)!

// Even though the runtime type is String, the compile-time type is Object

This distinction causes subtle bugs when developers expect runtime polymorphism.

Static Resolution Surprise

When Overloading Helps

Despite its pitfalls, overloading genuinely improves API usability in several scenarios.

1. Progressive Parameter Lists

Overloading shines when providing convenience methods that build on a fully-specified version:

progressive-overloads.java
Java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
public class HttpClient {
    // Full version with all options
    public HttpResponse send(HttpRequest request, HttpOptions options) {
        // Implementation with full control
    }
    
    // Convenience overload with default options
    public HttpResponse send(HttpRequest request) {
        return send(request, HttpOptions.defaults());
    }
}
 
public class StringBuilder {
    // Full version
    public StringBuilder append(CharSequence s, int start, int end) {
        // Implementation
    }
    
    // Convenience: append entire sequence
    public StringBuilder append(CharSequence s) {
        return append(s, 0, s.length());
    }
    
    // Convenience: append single char
    public StringBuilder append(char c) {
        return append(String.valueOf(c));
    }
}

2. Type-Specific Optimizations

Overloading allows optimized implementations for specific types while maintaining a general-purpose version:

public class Arrays {
    // General version using Object comparison
    public static <T> int indexOf(T[] array, T element) {
        for (int i = 0; i < array.length; i++) {
            if (Objects.equals(array[i], element)) return i;
        }
        return -1;
    }
    
    // Optimized version for primitives (avoids boxing)
    public static int indexOf(int[] array, int element) {
        for (int i = 0; i < array.length; i++) {
            if (array[i] == element) return i;
        }
        return -1;
    }
    
    // Similar overloads for long[], double[], etc.
}

3. Alternative Input Formats

When the same operation can accept data in different formats:

public class DateParser {
    public LocalDate parse(String dateString) {
        return LocalDate.parse(dateString);
    }
    
    public LocalDate parse(long epochMillis) {
        return Instant.ofEpochMilli(epochMillis)
            .atZone(ZoneId.systemDefault())
            .toLocalDate();
    }
    
    public LocalDate parse(int year, int month, int day) {
        return LocalDate.of(year, month, day);
    }
}

Good Overloading Characteristics

•Same semantic operation — All overloads do fundamentally the same thing
•Different input representations — Each overload accepts a different valid form of input
•Clear type distinctions — Parameter types are obviously different (String vs int, not List<String> vs List<Integer>)
•Delegation pattern — Simpler overloads delegate to fuller versions
•No behavioral surprises — Calling any overload produces predictable results

When Overloading Hurts

Overloading becomes dangerous when it introduces ambiguity, causes unexpected method selection, or creates brittle APIs.

1. Overloading with Related Types

Overloading methods where parameter types are related through inheritance causes resolution surprises:

related-types-problem.java
Java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
public class Printer {
    public void print(Collection<?> collection) {
        System.out.println("Collection: " + collection);
    }
    
    public void print(List<?> list) {
        System.out.println("List: " + list);
    }
    
    public void print(Set<?> set) {
        System.out.println("Set: " + set);
    }
}
 
// Problem: Which gets called?
Printer printer = new Printer();
Collection<?> items = new ArrayList<>(); // Declared as Collection
printer.print(items); // Calls print(Collection), not print(List)!
 
// The runtime type is ArrayList (a List), but the compile-time 
// type is Collection, so print(Collection) is selected.

2. Overloading with Autoboxing/Unboxing

Autoboxing in Java creates particularly insidious overloading problems:

autoboxing-problem.java
Java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
public class ListUtils {
    public static void remove(List<Integer> list, int index) {
        list.remove(index); // Removes element at index
    }
    
    public static void remove(List<Integer> list, Integer value) {
        list.remove(value); // Removes element by value
    }
}
 
List<Integer> numbers = new ArrayList<>(List.of(1, 2, 3));
 
// Which overload is called?
ListUtils.remove(numbers, 1); // Calls remove(list, int) — removes index 1
 
// To remove value 1, you need explicit boxing:
ListUtils.remove(numbers, Integer.valueOf(1)); // Removes value 1
 
// This is confusing and error-prone!

3. Overloading with Varargs

Varargs combined with overloading creates resolution nightmares:

varargs-problem.java
Java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
public class Logger {
    public void log(String message) {
        log(message, new Object[0]);
    }
    
    public void log(String message, Object... args) {
        System.out.printf(message, args);
    }
}
 
Logger logger = new Logger();
logger.log("Hello");           // Which one? Ambiguous in some cases!
logger.log("Hello", null);     // Is null the varargs array or an argument?
 
// Even worse with multiple varargs-like methods:
public void log(String... messages);     // Log multiple messages
public void log(String message, Object... args); // Format message
 
logger.log("a", "b"); // Compile error: ambiguous!

Dangerous Overloading Patterns

•Related types — Overloading with Collection/List/Set, Object/String, Number/Integer
•Primitive/Wrapper pairs — int/Integer, long/Long creates autoboxing confusion
•Multiple varargs — More than one varargs overload almost always causes problems
•Functional interfaces with same arity — Runnable vs Supplier, Consumer vs Function
•Null ambiguity — When null could match multiple overloads
•Generics with erasure — List<String> and List<Integer> are same at runtime

The Generics Erasure Trap

Overloading Resolution Rules

Understanding how compilers resolve overloads helps you predict and avoid problems.

Java Overload Resolution Algorithm

Java's resolution follows a multi-phase process:

Find applicable methods — Methods where arguments can be converted to parameter types
Among applicable methods, find most specific — The overload whose parameters are subtypes of all others
If no single most specific exists — Compile error (ambiguous)

Phase Details:

resolution-phases.java
Java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
public class Resolver {
    public void process(Object o) { }      // A
    public void process(String s) { }      // B
    public void process(Integer i) { }     // C
}
 
Resolver r = new Resolver();
 
// Call 1: process("hello")
// Applicable: A (String → Object), B (String → String exact)
// Most specific: B (String is more specific than Object)
r.process("hello"); // Calls B
 
// Call 2: process(42)
// Applicable: A (Integer → Object), C (int → Integer after boxing)
// Most specific: C (Integer more specific than Object)
r.process(42); // Calls C
 
// Call 3: process(new Object())
// Applicable: A only (Object → Object)
r.process(new Object()); // Calls A
 
// Call 4: What about...
Number num = 42;
// Applicable: A (Number → Object)
// C is NOT applicable: Number is not Integer
r.process(num); // Calls A, even though runtime type is Integer!

TypeScript Overload Resolution

TypeScript uses a different approach—overload signatures are tried in declaration order:

// TypeScript: order matters!
function format(value: string): string;
function format(value: number): string;
function format(value: Date): string;
function format(value: string | number | Date): string {
    if (typeof value === 'string') return value;
    if (typeof value === 'number') return value.toString();
    return value.toISOString();
}

// First matching signature wins
format("hello"); // Matches first overload
format(42);      // Matches second overload
format(new Date()); // Matches third overload

Test Overload Resolution

Guidelines for Safe Overloading

Apply these guidelines to keep overloading safe and intuitive:

Safe Overloading Guidelines

•Radically different parameter types — Overloads should have parameter types that are obviously and completely different. String and InputStream are clearly different; Collection and List are dangerously similar.
•Same semantic behavior — All overloads must do the same thing conceptually. Don't use overloading to provide different behaviors—that's what different method names are for.
•Delegate to canonical implementation — Simpler overloads should call through to the most complete overload. This ensures consistent behavior and reduces bug surface.
•Avoid overloading with related types — If types are related by inheritance or interface, reconsider. Use different method names instead.
•Never overload on functional interfaces — process(Runnable r) vs process(Supplier<T> s) with lambdas is a recipe for confusion.
•Test null explicitly — If null is a valid argument, test which overload it selects. Consider whether null should be valid at all.
•Document intended overload — In complex cases, document which overload should be called for ambiguous scenarios.

unsafe-overloading.java
Java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// UNSAFE: Related types
void process(Object o);
void process(String s);
void process(CharSequence cs);
 
// UNSAFE: Functional interfaces
void execute(Runnable r);
void execute(Callable<T> c);
 
// UNSAFE: Primitive/wrapper
void set(int value);
void set(Integer value);
 
// UNSAFE: Generic erasure
void handle(List<String> strs);
void handle(List<Integer> ints);

safe-overloading.java
Java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// SAFE: Radically different types
void load(File file);
void load(URL url);
void load(InputStream stream);
 
// SAFE: Different arities
void connect();
void connect(Config config);
 
// SAFE: Primitives + objects distinct
void print(int number);
void print(String text);
 
// SAFE: Different method names
void handleStrings(List<String> s);
void handleIntegers(List<Integer> i);

The Effective Java Rule

Alternatives to Overloading

Many scenarios where developers reach for overloading are better served by alternatives.

1. Static Factory Methods with Descriptive Names

Instead of overloaded constructors or factory methods, use distinctly named static factories:

factory-methods.java
Java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
// Instead of overloaded constructors:
// new User(String name)
// new User(String email, boolean verified)
// new User(ExternalUser external)
 
// Use named factory methods:
public class User {
    private User() { }
    
    public static User withName(String name) {
        User u = new User();
        u.name = name;
        return u;
    }
    
    public static User fromEmail(String email, boolean verified) {
        User u = new User();
        u.email = email;
        u.verified = verified;
        return u;
    }
    
    public static User fromExternal(ExternalUser external) {
        User u = new User();
        u.externalId = external.getId();
        u.name = external.getDisplayName();
        return u;
    }
}
 
// Call sites are self-documenting:
User.withName("Alice");
User.fromEmail("alice@example.com", true);
User.fromExternal(externalUser);

2. Builder Pattern

For methods with many optional parameters, builders eliminate overloading entirely:

// Instead of:
sendEmail(to);
sendEmail(to, subject);
sendEmail(to, subject, body);
sendEmail(to, subject, body, attachments);
sendEmail(to, subject, body, attachments, options);

// Use a builder:
Email.to("user@example.com")
    .subject("Hello")
    .body("Content here")
    .attach(file1, file2)
    .withOption(EmailOption.TRACK_OPENS)
    .send();

3. Parameter Objects

Consolidate related parameters into an object:

// Instead of:
void search(String query);
void search(String query, int limit);
void search(String query, int limit, int offset);
void search(String query, int limit, int offset, SortOrder sort);

// Use a request object:
Record SearchRequest(String query, int limit, int offset, SortOrder sort) {
    // Provide defaults via factory methods
    public static SearchRequest of(String query) {
        return new SearchRequest(query, 10, 0, SortOrder.RELEVANCE);
    }
}

void search(SearchRequest request);

4. Method Name Variants

For semantically different operations, just use different names:

// Instead of ambiguous overloads:
void log(String message);
void log(Exception e);
void log(String message, Exception e);

// Use clear names:
void logMessage(String message);
void logException(Exception e);
void logError(String message, Exception cause);

Python's Approach

Language-Specific Considerations

Different languages handle overloading differently. Understanding these differences is crucial when designing cross-language APIs or working in polyglot environments.

Java Overloading

Full overloading support with compile-time resolution
Autoboxing creates int/Integer ambiguity
Generic type erasure prevents List<A>/List<B> overloads
Varargs complicates resolution
Return type alone cannot distinguish overloads

// Valid overloads
void process(String s);
void process(int i);
void process(String s, int i);

// Invalid: return type only
// String getValue();
// int getValue(); // ERROR: duplicate method

// Invalid: erasure
// void handle(List<String> s);
// void handle(List<Integer> i); // ERROR: same erasure

Java Best Practice: Use overloading sparingly. Prefer named factory methods, builders, or distinct method names when there's any ambiguity risk.

Summary: Overloading with Discipline

Key Takeaways

•Overloading is static — The compile-time type determines which overload is called, not the runtime type. This surprises many developers.
•Use radically different types — Overload only when parameter types are obviously and completely different. String vs. File: good. List vs. Collection: dangerous.
•Same semantics required — All overloads must do the same conceptual operation. Different behaviors need different method names.
•Delegate to canonical version — Simpler overloads should call through to the most complete version, ensuring consistent behavior.
•Avoid related types — Inheritance hierarchies, boxing pairs, and generic erasure all create hazards. When in doubt, use distinct names.
•Consider alternatives — Named factory methods, builders, and parameter objects often work better than overloading.
•Know your language — Overloading rules vary. Java erases generics. TypeScript uses signature ordering. Python and Go don't support overloading.
•Test edge cases — Explicitly test null handling, boxing, and subtype arguments to verify correct overload selection.

Module Complete

You've now mastered all four pillars of method signature design:

Method Naming — Revealing intent through precise, consistent vocabulary
Parameter Design — Creating intuitive, type-safe, hard-to-misuse parameters
Return Types — Communicating results and handling all outcomes gracefully
Overloading — Using power wisely to create flexible yet predictable APIs

Together, these skills enable you to design method signatures that make APIs intuitive, safe, and a pleasure to use.

Module Complete

4 / 4