Operator-Style API Design

Starter: think before typing

Before running this readable interfaces example, find the line where the main idea becomes active. Write a prediction: what must already be true for that line to work, and what should be different after it runs? The checked run ends with `120p`; predict how the focus line helps produce that evidence.

Learning Objectives

• Explain why some languages let operators call functions.
• Design readable Java methods instead of clever syntax.
• Avoid APIs that look simple but do expensive or surprising work.
• Balance expressiveness against maintainability.

Learning Outcomes

• By the end of the lesson, you can explain why some languages let operators call functions.
• By the end of the lesson, you can design readable Java methods instead of clever syntax.
• By the end of the lesson, you can avoid APIs that look simple but do expensive or surprising work.
• By the end of the lesson, you can balance expressiveness against maintainability.

Why this idea exists

Operator-style API design exists because readable programs often feel close to the language of the problem: adding money, comparing dates, combining paths or applying transformations.

Some languages allow operator overloading so symbols such as `+` can call user-defined behaviour. Java mostly avoids that feature, so Java programmers must design clear method names that carry the same expressive intent without hiding surprising work.

This lesson fits the arc by shifting attention from whether code works to how code reads. A good API makes valid use obvious, invalid use awkward and expensive behaviour visible enough for maintainers to trust.

Deep dive

Lesson visual

Type this and run it

Create OperatorStyleApiDesignDemo.java, type the program, and run it before changing anything. This section is about reproducing the checked baseline.

public class OperatorStyleApiDesignDemo {
  public static void main(String[] args) {
    Money price = new Money(100);
    Money tax = new Money(20);
    Money total = price.plus(tax);
    System.out.println(total);
  }
}

record Money(int pence) {
  Money plus(Money other) {
    return new Money(pence + other.pence);
  }

  public String toString() {
    return pence + "p";
  }
}

Build and run it with:

javac OperatorStyleApiDesignDemo.java && java OperatorStyleApiDesignDemo

Expected baseline: 120p

Line-by-line explanation

Read the code as a sequence of responsibilities. The focus line for this lesson is Money price = new Money(100);; the surrounding lines prepare it, use its result or make the behaviour observable.

Worked example

Trace the program

Common misconception

A common mistake in operator-style api design is treating the example as a finished answer. For readable interfaces, the important question is narrower: which operation carries the idea, what does it make possible, and what would break if you changed it carelessly?

Quick checks

How to study this lesson

For Operator-Style API Design, predict how readable interfaces changes the run before you press Run.

Use the first portfolio task as your main edit: Design method names for a tiny Money class.

Use the second task as your variation: Explain why Java does not let you overload + for your class.

Finish with evidence, not a diary entry: Identify one API that looks neat but hides too much work.

Portfolio Practice

1. Design method names for a tiny Money class.
2. Explain why Java does not let you overload + for your class.
3. Identify one API that looks neat but hides too much work.

Final self-check

Study route

Practise readable interfaces by predicting the Java example, typing it, running it in the browser, tracing the result and saving portfolio evidence.

Next, move into Generic Reuse and carry forward one improvement from this lesson into the next program.