Method Overloading

Overloading means several methods share a name but differ in parameter list. The compiler chooses between them using the types of the arguments at the call site, applying a fixed order: an exact match wins first, then widening primitive conversions, then boxing and unboxing, and finally a widening reference conversion. The most specific applicable method is chosen.

public class Main {
    public static void main(String[] args) {
        Printer p = new Printer();
        p.print("hello");
        p.print(42);
        p.print(3.5, 2);
    }
}

class Printer {
    void print(String text) { System.out.println("text: " + text); }
    void print(int number) { System.out.println("int: " + number); }
    void print(double number, int times) {
        for (int i = 0; i < times; i++) {
            System.out.println("double: " + number);
        }
    }
}

The output shows three distinct resolutions. The string argument picks the single-parameter string version, the integer picks the int version, and the two-argument call picks the version that takes a double and an int. Notice that the int argument is widened to a double in the last case, because no overload accepts a double and an int exactly, but one does accept a double and an int after widening.

Two overloads are ambiguous when neither is more specific than the other for the arguments supplied, such as a method taking a long and one taking a double called with an int literal. The compiler reports the ambiguity rather than picking one, which is the right behaviour.

The risk to watch for is that adding an overload can change how existing code compiles. If a call was previously resolved to one method and a new overload is a better match, the call silently switches to the new method. That is why some teams restrict overloading to a small, coherent family rather than scattering it across a class.

Method overloading is giving a class several methods with the same name but different parameter lists, so callers can use one name for an operation that accepts different shapes of input. The compiler picks the right one from the argument types, so the caller does not have to choose between differently named methods.

It reads well when the variants are genuinely the same concept. A print method that accepts a string, an integer or a formatted number is one operation to the reader. A builder with a fluent chain, or a factory with several overloads for common cases, is the same idea.

Overloading is a poor fit when the variants are different operations that happen to share a word. If one overload sends an email and another charges a card, a single name makes the class harder to read, and a static analysis tool will warn about it.

Two practical cautions. Do not overload on the null literal, because there is no way to tell which reference overload the caller meant. And do not overload with a subtype relation that creates ambiguity, such as an overload taking an Object alongside one taking a String, because a null or a general reference becomes ambiguous at the call site.

Because overload resolution is done at compile time against the set of methods that exist at that moment. When you add a method, the compiler re-evaluates every call site in the codebase, and a call that previously resolved to one method may now resolve to the new one instead. The source did not change and the behaviour did change, which is exactly the kind of surprise that is expensive to debug.

The classic case is adding an overload that accepts a supertype of an existing parameter. A method taking a CharSequence added next to one taking a String means calls with a String argument now bind to the more specific String version, which may behave differently. The reverse also happens: adding an overload that accepts a subtype can capture calls that previously went somewhere else, and calls with a null literal become ambiguous and stop compiling.

Another failure mode is when the new overload is not applicable to every existing call. A method that throws a checked exception, or that behaves differently for edge cases such as null or empty input, will silently change the behaviour of code that happened to match it.

The defensive habits are worth naming. Keep overloads in one place and keep them a coherent family. Use distinct names when the variants are not really the same operation. Treat adding an overload to a public class as an API change, with the same care you would give changing a method body, and make sure the whole test suite runs before it ships.