Prism: [XF] Rename IPageDialogService methods to remove "Async"

[brianlagunas]

Right now the IPageDialogService method names all have "Async" at the ends. I am not sure why we did this, but I think they should be removed.

• DisplayAlertAsync --> DisplayAlert
• DisplayActionSheetAsync --> DisplayActionSheet

What is the community thoughts?

Probably not worth a breaking change?

[bartlannoeye]

TL;DR: methods returning a Task should have the suffix Async.

It's best practice to name all async (Task based) methods Async. This not only makes the API clear to the programmer (who might just see it with IntelliSense) but also to a possible code reviewer, flagging forgotten await calls much easier.

But who am I? So a quote by Stephen Toub:

If a public method is Task-returning and is asynchronous in nature (as opposed to a method that is known to always execute synchronously to completion but still returns a Task for some reason), it should have an “Async” suffix. That’s the guideline. The primary goal here with the naming is to make it very obvious to a consumer of the functionality that the method being invoked will likely not complete all of its work synchronously; it of course also helps with the case where functionality is exposed with both synchronous and asynchronous methods such that you need a name difference to distinguish them. How the method achieves its asynchronous implementation is immaterial to the naming: whether async/await is used to garner the compiler’s help, or whether types and methods from System.Threading.Tasks are used directly (e.g. TaskCompletionSource) doesn’t really matter, as that doesn’t affect the method’s signature as far as a consumer of the method is concerned.

Of course, there are always exceptions to a guideline. The most notable one in the case of naming would be cases where an entire type’s raison d’etre is to provide async-focused functionality, in which case having Async on every method would be overkill, e.g. the methods on Task itself that produce other Tasks.

As for void-returning asynchronous methods, it’s not desirable to have those in public surface area, since the caller has no good way of knowing when the asynchronous work has completed. If you must expose a void-returning asynchronous method publicly, though, you likely do want to have a name that conveys that asynchronous work is being initiated, and you could use the “Async” suffix here if it made sense. Given how rare this case should be, I’d argue it’s really a case-by-case kind of decision.

I hope that helps, Steve

[mmbeyrem]

Hi

We may rename the interface IPageDialogService to IPageDialogServiceAsync,
if we believe all methods will be based on await async

2017-01-27 9:08 GMT+01:00 Bart Lannoeye [e-mail]:

TL;DR: methods returning a Task should have the suffix Async.

It's best practice to name all async (Task based) methods Async. This not
only makes the API clear to the programmer (who might just see it with
IntelliSense) but also to a possible code reviewer, flagging forgotten
await calls much easier.

But who am I? So a quote by Stephen Toub:

If a public method is Task-returning and is asynchronous in nature (as
opposed to a method that is known to always execute synchronously to
completion but still returns a Task for some reason), it should have an
“Async” suffix. That’s the guideline. The primary goal here with the naming
is to make it very obvious to a consumer of the functionality that the
method being invoked will likely not complete all of its work
synchronously; it of course also helps with the case where functionality is
exposed with both synchronous and asynchronous methods such that you need a
name difference to distinguish them. How the method achieves its
asynchronous implementation is immaterial to the naming: whether
async/await is used to garner the compiler’s help, or whether types and
methods from System.Threading.Tasks are used directly (e.g.
TaskCompletionSource) doesn’t really matter, as that doesn’t affect the
method’s signature as far as a consumer of the method is concerned.

Of course, there are always exceptions to a guideline. The most notable
one in the case of naming would be cases where an entire type’s raison
d’etre is to provide async-focused functionality, in which case having
Async on every method would be overkill, e.g. the methods on Task itself
that produce other Tasks.

As for void-returning asynchronous methods, it’s not desirable to have
those in public surface area, since the caller has no good way of knowing
when the asynchronous work has completed. If you must expose a
void-returning asynchronous method publicly, though, you likely do want to
have a name that conveys that asynchronous work is being initiated, and you
could use the “Async” suffix here if it made sense. Given how rare this
case should be, I’d argue it’s really a case-by-case kind of decision.

I hope that helps, Steve

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
https://github.com/PrismLibrary/Prism/issues/918#issuecomment-275610297,
or mute the thread
https://github.com/notifications/unsubscribe-auth/ALko0dykL1YHpfMMHfEb3K2G3CBEsXHkks5rWaYXgaJpZM4LvTdR
.

[brianlagunas]

I'll just leave it as-is then :) It was just a thought

[lock[bot]]

This thread has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.