Discussion: 'Async' suffix in the names of methods

[dbeuchler]

I came across this while implementing the async lifecycle for modules, resources, and plugins.

I renamed methods to applied the Suffix Async to the changed methods and APIs. After that I thought about if it is required to write the Async suffix.

I investigated in research:

The .NET style convention is to add the "Async" suffix to all asynchronous method names. This approach helps to more easily differentiate between synchronous and asynchronous methods. Certain methods that aren't explicitly called by your code (such as event handlers or web controller methods) don't necessarily apply in this scenario. Because these items aren't explicitly called by your code, using explicit naming isn't as important. Microsoft Docs

That would mean:

• Suffix is required to differentiate between synchronous and asynchronous methods
• Suffix is not required on methods that aren't explicitly called by api users

But: does it mean when there is no synchronous API, that the suffix is not required?

Further investigation:

Framework Design Guidelines (Microsoft Press), Authors: Krzysztof Cwalina & Brad Abrams, Edition: 2nd (and also in later editions)

You should use the 'Async' suffix in the names of methods that have asynchronous counterparts.
This helps developers easily distinguish between the synchronous and asynchronous versions of a method.
When providing both synchronous and asynchronous versions of a method, use the same base name and add 'Async' to the asynchronous version.

That would mean:

• The Async suffix becomes mandatory when a synchronous version exists — otherwise method names would collide or confuse users.
• when there is no synchronous API, the suffix is not required

Discussion

• Do we need the Async suffix on our APIs, like facades, or plugins?

Discussion wanted: @1nf0rmagician @seveneleven @andreniggemann

[1nf0rmagician]

While I respect the Framework Design Guidelines I think the Microsoft Docs are quite clear here, The .NET style convention is to add the "Async" suffix to all asynchronous method names.

So I would conclude, yes we need the 'Async' Suffix on all async methods of our facades and plugins.

It also feels more clear to me, I think I have never seen an async method without the prefix und would be quite confused by it, personally 😅