Operator Overloading (do’s & don’ts)

Operators should preserve familiar expectations

Operator functions provide syntax for established operations such as addition, comparison, indexing, and invocation. The operator's meaning should remain unsurprising for the domain.

Copy codedata class Minutes(val value: Int) {
    init { require(value >= 0) }
    operator fun plus(other: Minutes): Minutes =
        Minutes(Math.addExact(value, other.value))
}

fun main() { check(Minutes(10) + Minutes(15) == Minutes(25)) }

This JVM example checks overflow instead of silently wrapping. Addition returns a new value and leaves both operands unchanged. Using + to save a record or perform network I/O would hide a surprising side effect.

Operators do not automatically implement related contracts. If you define ordering, verify that it is consistent with your domain's equality rules when sorted collections rely on both.

Exercise

Implement subtraction with a documented nonnegative-result rule. Test equal operands, a smaller right operand, and a larger right operand.

Check: explain whether invalid subtraction throws, returns a signed type, or uses an explicit result, and keep that choice consistent with the type's invariant.

Reference: Operator overloading