Guidance around impl Trait

[dtolnay]

This can wait until closer to stabilization rust-lang/rust#34511.

When should you consider using impl Trait? What are some reasons you should consider not using impl Trait?

In the url evaluation we discussed how Result<T, impl Error> is bad because the caller cannot handle it with ?. This seems like a general concern that extends to lots of cases other than Error.

[dtolnay]

From servo/rust-url#305 (comment):

Guideline question: some of these types only exist (or are only public) because the language does not support -> impl Iterator<Item=Foo> yet. When it does, will it be recommended that everything uses -> impl Iterator<Item=Foo> + Debug?

[N-Maas]

This discussion is a bit older, but maybe it can be revived?

Impl Trait seems like a topic where guidelines might be useful. I think impl Trait in parameter position doesn't need a guideline, as it is mostly equivalent to a generic with trait bound (except it can't be specified explicitely in the function call). However, impl Trait in return types is quite another thing and needs some consideration at least for libraries. The alternative is, of course, returning a type specifically declared for this purpose, the same way e.g. the standard library does it for iterators.

I know of the following advantages when using impl Trait:

• It might require less code, because no new struct needs to be implemented (which should not be an important argument for library code).
• The caller can not depend on any implementation details. As the struct's public API usually will only include it's declaration and the trait implementation(s), this should only concern generic type arguments of the struct. It means that trait bounds can be added and/or the number of generic arguments can be changed without breaking backwards compatibility, which would not be possible with a concrete return type.

However, the additional freedom for authors of the API comes with some severe drawbacks for consumers. I think they can be summarized as "the user can't name the type". This includes at least the following two concrete problems:

• Defining a struct that contains the returned type becomes quite cumbersome, it is only possible via a generic argument with the corresponding trait bound. This generic/trait bound also propagates to any function using the struct.
• Probably even worse, the type can't be used for associated types in traits. The workaround would require a new generic parameter for the trait, which isn't semantically equivalent anymore and of course a lot of boilerplate. (I think in some cases even type inference doesn't work when generics instead of associated types are used, e.g. for some kinds of blanket implementations?)

Thus, it seems to me that libraries should generally avoid using impl Trait in the return type of a public API. Or if they currently really need the additional flexibility, they should at least strive to eventually converge to a state that is stable enough to use a concrete type. (Replacing impl Trait with a concrete type implementing this trait isn't a breaking change, right?)

[BurntSushi]

Yeah. I think the guideline should be as simple as this:

Do not use impl Trait in the public API of a library unless you have no other choice. (For example, to return an unboxed anonymous type, such as a closure.) This advice may change if impl Trait becomes more flexible in the future.

Using it in argument position is perhaps a bit more defensible, but giving up the caller's ability to explicitly specify the type via turbofish doesn't seem worth the mostly stylistic argument in favor of impl Trait in the argument position.

[N-Maas]

Do not use impl Trait in the public API of a library unless you have no other choice. (For example, to return an unboxed anonymous type, such as a closure.)

Note that you can almost always avoid using an anonymous type by implementing it as a struct instead. And I think libraries should do that. The only reason you really can't is probably if you already got an anonymous type from another API that you are using internally.

[N-Maas]

So, should I open a PR to include such a guideline? Maybe under Flexibility, C-IMPL-TRAIT? Or rather Interoperability?