Is the “Async” suffix used in the method name depending on whether the “async” modifier is used?

Question

What is the convention for a method name suffix with "Async"?

Should the suffix "Async" be added only to the method declared using the async modifier?

 public async Task<bool> ConnectAsync() 

Or is it enough that the method simply returns Task<T> or Task ?

 public Task<bool> ConnectAsync() 

Answer 1

I think the truth is ambiguous even from Microsoft documentation:

In Visual Studio 2012 and the .NET Framework 4.5, any method that is associated with the async ( async in Visual Basic) is considered an asynchronous method, and C # and Visual Basic compilers perform the necessary transformations to implement the method asynchronously using TAP. The asynchronous method should return either a Task object or a Task<TResult> .

http://msdn.microsoft.com/en-us/library/hh873177 (v = vs .110) .aspx

This is no longer the case. Any method with async is asynchronous, and then says that it should return either Task or Task<T> - which is not suitable for methods at the top of the call stack, such as Button_Click or async void .

Of course, you should consider what is the point of the convention?

We can say that the async suffix convention is to tell the user the API that the method is expected. For the method to be expected, it must return Task for void or Task<T> for the return method, which means that only the latter can be a suffix with async .

Or you can say that the async suffix convention is to let the method know that it can return immediately, discarding the current thread to do other work and potentially causing a race.

This quote from Microsoft states:

By convention, you add "Async" to the names of methods that have an Asynchronous or Asynchronous modifier.

http://msdn.microsoft.com/en-us/library/hh191443.aspx#BKMK_NamingConvention

Which does not even mention that your own asynchronous methods returning Task need the async suffix, which, I think, we all agree on what they do.

---

Thus, the answer to this question may be as follows: both. In both cases, you need to add async to the methods with the async and return Task or Task<T> .

---

I will ask Stephen Tub to clarify the situation.

Update

So I did. And here is what our good man wrote:

If the public method is a task return and is asynchronous in nature (as opposed to a method that, as you know, always runs synchronously with but still returns the task for some reason), it should have the suffix "Async". This is a guide. The main purpose of naming here is to make it very obvious to the consumer the functionality that calls the method will most likely not complete all its work synchronously; this, of course, also helps in the case where the functionality is exposed to synchronous and asynchronous methods, so you need to distinguish names to distinguish them. How the method achieves its asynchronous implementation does not matter for naming: whether async / await is used to collect compiler help, or are the types and methods from System.Threading.Tasks used directly (for example, TaskCompletionSource) really does not matter, since this does not affect on signature methods in relation to the consumer method.

Of course, there are always exceptions to the manual. The most noticeable in the case of naming will be cases where integer raison detre types should provide asynchronous focusing functionality, and in this case, the presence of Async for each method will be excessive, for example. methods of the Task itself, which produce other tasks.

As for asynchronous methods that return voids, it is undesirable to have those in the public surface area, since the caller does not have a good way of knowing when the asynchronous operation is completed. If you have to expose a public asynchronous method that returns void, although you probably want to have a name that conveys that asynchronous operation and you can use the suffix "Async" here if that makes sense. Given how rare this case should be, Id proves that this is valid on a case-by-case basis.

I hope this helps, Steve

A quick guide from Stevens' introductory sentence is clear enough. This eliminates async void because it is unusual to create a public API with this design, since the correct way to implement asynchronous void is to return a simple instance of Task and let the compiler do its magic. However, if you need public async void then adding async recommended. Other top-of-stack async void methods, such as event handlers, are usually not public and have no value / qualification.

For me, this tells me that if I wonder about the async suffix on async void , I probably should turn it into an async Task so that callers can wait for it and then add async .

Answer 2

What is the convention for a method name suffix with "Async".

A task-based asynchronous template (TAP) requires that methods always return Task<T> (or Task ) and are named with the suffix Async; it does not depend on using async . Both Task<bool> Connect() and async Task<bool> Connect() will compile and run just fine, but you will not abide by the TAP naming convention.

If the method contains an async modifier, or is it enough to just return the task?

If the body of the method (regardless of type or return name) includes await , you should use async ; and the compiler will tell you: "The wait statement can only be used in the asynchronous method ...". Returning Task<T> or Task not enough to avoid using async . See async for more details (C # link) .

those. which of these signatures is correct:

Both async Task<bool> ConnectAsync() and Task<bool> ConnectAsync() properly follow TAP conventions. You can always use the async , but you will get a compiler warning "This asynchronous method does not use" wait "and will work synchronously ..." if the body does not use await .

Answer 3

or is it enough that it just returns the task?

It. The async is not a real issue here. If you implement asynchrony without using the async , the method still remains “Async,” in a general sense.

Answer 4

Since Task and Task<T> are both expected types, they are some kind of asynchronous operation. Or at least they should represent.

You should add the Async suffix to the method, which in some cases (not necessarily all) does not return a value, but rather returns a wrapper around the current operation. This shell is usually Task , but on Windows RT it may be IAsyncInfo . Watch your gut feeling and remember that if the user of your code sees the Async function, he or she will know that the call to this method is separate from the result of this method and that they need to act accordingly.

Note that there are methods like Task.Delay and Task.WhenAll that return Task without the Async suffix.

Also note that there are async void methods that are fire and forget the asynchronous method, and you better know that the method is constructed in this way.

Answer 5

In Asynchronous Programming with Asynchronous and Pending (C #) , Microsoft offers the following guide:

Naming convention

By convention, you add "Async" to the names of methods that are asynchronous .

You can ignore the convention in which the event, base class or interface of the contract offers a different name. For example, you should not rename generic event handlers such as Button1_Click .

I find this manual incomplete and unsatisfactory. Does this mean that in the absence of the async modifier, this method should be called Connect instead of ConnectAsync ?

 public Task<bool> ConnectAsync() { return ConnectAsyncInternal(); } 

I do not think so. As pointed out by @Servy's short answer , and even more so by a detailed answer from @Luke Puplett , I believe that it is quite appropriate and really to expect this method to be called ConnectAsync (because it returns the expected one), Further supporting this by @John Skeet in this answer in another question is added by async to the method name, regardless of the availability of the async modifier.

Finally, for another question , consider this comment by @Damien_The_Unbeliever :

async/await are implementation details of your methods. This is important not just one jot, whether your async Task Method() method is declared or just Task Method() , as for your callers. (In fact, you can freely change these two times, not counting it changing.)

From this, I conclude that it is the asynchronous nature of the method that determines what it should be called. The user of the method does not even know if the async modifier is used in its implementation (without C # or CIL source code).

Answer 6

I would say that it should use the Async suffix if it returns a task, regardless of whether the method is declared using the async modifier.

The reason for this is because the name is declared in the interface. The interface declares the return type, which is Task . Then there are two implementations of this interface, one implementation implements it using the async modifier, and the other does not.

 public interface IFoo { Task FooAsync(); } public class FooA : IFoo { public Task FooAsync() { /* ... */ } } public class FooB : IFoo { public async Task FooAsync() { /* ... */ } } 

Answer 7

I create many API services and other applications called other systems where most of my code runs asynchronously.

Own rule of thumb that I adhere to:

If there is both a non-asynchronous and asynchronous method returning the same, I am a suffix asynchronous with Async. Otherwise, no.

<strong> Examples:

Only one method:

 public async Task<User> GetUser() { [...] } 

The same method with two signatures:

 public User GetUser() { [...] } public async Task<User> GetUserAsync() { [...] } 

This makes sense since it returns the same data, but the only thing that is different is the way the data is returned, not the data itself.

I also think that these naming conventions exist because of the need to introduce asynchronous methods and still maintain backward compatibility.

I argue that the new code should not use the Async suffix. This is as obvious as the return type of String or Int, as mentioned earlier in this thread.