In Dart, do I annotate a function return value with dynamic or Object if I don't know it's type?

Question

If I have a function that returns a value of an unknown type, do I use dynamic, representing any object, or Object, which is the ancestor of all other types?

The style guide discusses this question for parameters, but not for return values.

How should I annotate the return value and why?

Answer 1

Dart engineer Bob Nystrom writes:

Return types are an interesting twist on this problem. With parameter types, the guidelines are pretty straightforward:

1. If you use Object as a parameter type, you're saying "my method will safely accept any object and only use it for stuff like toString() that all objects support".

2. If you use dynamic (or nothing) as a parameter type, you're saying "Dart's type system can't easily express the type that I accept here" or "I didn't bother to annotate".

It's tricky to flip (1) around. For a return type, I guess Object would say "You better not call anything except toString() or other stuff all objects support before doing a type test yourself", where dynamic would I think mean "we can't easily annotate this so you and I better just know what we're doing".

The user would have to "cast" it to a specific type that they expect to see to avoid compiler warning and get an error earlier in checked mode.

For what it's worth, in many cases you wouldn't have to cast even if you return Object. Dart allows implicit downcasting when you initialize a local variable with a type annotation. So you can do:

Object foo() => 123;

main() {
  int x = foo(); // Implicit downcast. No type warning.
}

I think in this case, I would probably do dynamic, though. I think that conveys "I don't know what type this returns, but you should" better than Object.