Return types make a refactor fail at the boundary

A docblock @return is a comment; the engine never reads it, so a method that starts returning null on a Tuesday fails somewhere else on a Thursday. A real return type moves the failure to the method that broke the promise.

public function find(int $id): Product
{
    // returning null here is now a TypeError, raised here,
    // rather than a fatal in whatever called it
    return $this->rows[$id] ?? throw_not_found($id);
}

The value is not the type checking, which a static analyser could do — it is that the stack trace points at the cause instead of the symptom. Adding them to an existing codebase is best done leaf-first, because a return type on a method that everything calls will surface every latent inconsistency at once. Note there is no nullable syntax until 7.1, so this year a method that can legitimately return nothing gets no type at all.