Decide whether to use Promise/then() or async/await in example code

[peterflynn]

Topic

This is an issue regarding:

• The tutorials contained within this repo.
• The samples contained within this repo.

Description of the issue

We're currently not very consistent about whether sample code uses Promises directly with then() vs. the new async/await syntax. In some cases, like the "How to make network requests" tutorial, we mix & match both together in a single document.

Should we standardize on one syntax and try to use it everywhere?

[pklaschka]

To be honest, I don't think standardizing this would be a good idea. There simply are cases where one or the other is more readable. This, in my opinion, especially shows in the doc page you've mentioned. Here, xhrBinary(url) is a typical function in which, also if I wrote the code for my plugin, I'd use the "old" syntax. It simply is easier to read (with multiple reject statements etc.). Also,

req.onerror = reject;
req.onabort = reject;

in this example make the "old" syntax useful.

On the other hand, below, in downloadImage(selection, jsonResponse), the new syntax makes this easy to understand (with the traditional syntax, this would be a very deep tree of callbacks). Therefore, there is a case to make for the new syntax in that case.

Looking at these examples and how they are more readable with different syntax(es) (no idea what the plural of syntax is 😆), I think standardizing this would be standardization just for the sake of standardization, lowering readability in some cases. All in all, I therefore think there is a case to be made against standardizing it...