Functions documentation are not clear about consequence of missing return type

[julemand101]

Page URL

https://dart.dev/language/functions

Page source

No response

Describe the problem

I feel the current documentation of "Functions" contains a foot-gun for beginners since it contains the following description:

Although Effective Dart recommends type annotations for public APIs, the function still works if you omit the types:

isNoble(atomicNumber) {
 return _nobleGases[atomicNumber] != null;
}

I am aware that at this step in the documentation, it might be a bit early to introduce the concept of dynamic, but I do think it is misleading to use the wording "the function still works if you omit the types".

Yes, theoretically, it works. But it sounds like by omitting type we are getting same behavior as if we do when specifying the return-type (and the types are just something recommended by Effective Dart) which is not the case, since Dart will assume the returned type are dynamic unless we are defining a local scoped function.

Users will first later on in their journey begin to find it weird that auto-completion does not fully work and they get runtime errors which the compiler should have been able to catch statically.

Overall, I don't really think it is a good idea to suggest that removing the return-type is a possible solution unless it is explicit mentioned that Dart will assume dynamic unless it is a local defined function. At least, it does not provide any benefit for the user if they omit the return type.

Also, based on the amount of users I see thinking "no return-type specified" means "void", I will suggest that it is mention explicit that in Dart, we use void as return-type for functions that does not return anything. Again, before no return-type ends up meaning dynamic which opens up for issues the compiler should have been able to identify statically.

Expected fix

No response

Additional context

No response

I would like to fix this problem.

• I will try and fix this problem on dart.dev.

[sfshaza2]

That seems like a reasonable point, @julemand101.