It does provide some type-level information, but if you're already writing documentation, the benefits are marginal. Add to that the fact that it really pollute

It does provide some type-level information, but if you're already writing documentation, the benefits are marginal. Add to that the fact that it really pollutes your interfaces, I would argue that it is almost always better to just pass a null and force people to check it, or read the documented guarantees. Basically, just assume every Java type is wrapped in Optional implicitly. But by adding Optional (and using it in standard libraries) it's often a matter dealing with code that interfaces between the two styles -- another problem that didn't exist without Optional. And even if you think Optional is worth the small gains, it's still a sad mimic of the Option types implemented in other languages.