What should the ending of IAsyncEnumerable methods and variables be? Do we need a convention?

[virzak]

I've seen no ending, Async, AsyncEnumerable, etc. for methods.

For variables if I have a method IAsyncEnumerable<Posts> GetPostsAsync()

Should I assign it to postsEnumerable variable?

I looked in the code of dotnet org and seems like there's not convention on this.

[stephentoub]

Our convention is to use an Async suffix.

[virzak]

System.Linq.Async ends all their IAsyncEnumerables with Await (eg. ZipAwait). Good to know to avoid that convention.

[virzak]

@stephentoub why is your new Select is not SelectAsync? I assume this is because it doesn't have async modifier? Still, instinctively I was typing SelectAsync because I was passing and receiving IAsyncEnumerable.

https://github.com/dotnet/runtime/blob/7cb94d12d21791f08fe069d845014beb6706842c/src/libraries/System.Linq.AsyncEnumerable/src/System/Linq/Select.cs#L24C49-L57

[stephentoub]

#79782 (comment)

[neon-sunset]

Unless you plan to offer both synchronous and asynchronous versions, a method should plainly indicate what it returns and should not use async suffix: GetPosts().

Similar logic applies to variables: please do not name them thingsEnumerable. C# is a strongly typed language, and types already carry more than enough information. Variables can follow a plain naming scheme: posts, things, books, etc.

Keep in mind that CoreLib and .NET internals are subject to an outdated convention that cannot be changed due to consistency and high explicitness considerations. However, luckily, the code outside can follow a less cumbersome convention.

[tannergooding]

This is directly contrary to the framework design guidelines and creates an inconsistent API surface, both across differing libraries and over time if you need to version in the future.

The official recommendation, as per FDG 9.2.2 Task-Based Async Pattern, DO use the suffix "Async" when naming an asynchronous method.

[neon-sunset]

It is true, but (sadly or luckily) FDG is outdated and contributes to the decline of popularity of .NET by refusing to promote concise and highly readable code style. Following it requires caution and for new code should be avoided in order to realize strengths of .NET and the languages it offers.

A method already returns an awaitable type. There is no reason to write GetUserClass everywhere if there is only one user type. If this ever changes a breaking change by the library must be taken instead. But such condition is exceedingly rare and does not excuse the bloat which .NET ecosystem is sometimes associated with.

[tannergooding]

You are free to form your own opinions. However, it is inaccurate to say it is outdated as the 3rd edition was fairly recently published, explicitly to account for modern .NET, evolutions of the language, etc. This included explicit deprecation of rules that were considered outdated.

The Async suffix guideline was one that was very explicitly kept and with the reasons given in the book. The overall consistency across the entire ecosystem, flexibility to evolve APIs over time, and more wins out. There are of course exceptional cases, like some of the LINQ APIs that Stephen linked to above, but they come with well reasoned nuance on why that particular case wins out (which is largely based around ensuring existing tooling works).

A method already returns an awaitable type. There is no reason to write GetUserClass everywhere if there is only one user type. If this ever changes a breaking change by the library must be taken instead.

This reasoning is in direct contrast to the reasoning given in the FDG. Binary breaking changes should be a last resort and are often considered unacceptable, particularly for things like the core libraries or most underlying frameworks. One of the most praised strengths of .NET is that we remain binary compatible.

But such condition is exceedingly rare and does not excuse the bloat which .NET ecosystem is sometimes associated with.

You will find people that complain and people that praise on any point. .NET as a whole is more praised on its robust standard library, consistent API surface, and understandable names than it is degraded for the points you've called out. It is the reason .NET continues to see an uptake in adoption and is consistently one of the most loved languages/ecosystems in the well-known yearly survey's (such as by StackOverflow).