More Descriptive Errors (Part 1/2)

[KtorZ]

Issue Number

#260

Overview

• I have reviewed some error data-types and constructors to make them more consistent with the rest.
• Added more extensive descriptions and reviewed some errors code to provide a better feedback to users of the API and/or CLI.

Comments

Waiting for @jonathanknowles to control the English here 😛

A few examples:

{"code":"wallet_already_exists","message":"This operation would yield a wallet with the following id: 23c401a00f94d05e3e48599ed85cc5ea0e16a2b6. However, I already know a wallet with such id!"}

{"code":"no_such_wallet","message":"I couldn't find a wallet with the given id: 2512a00e9653fe49a44a5886202e24d77eeb998f."}

[jonathanknowles]

Hi @KtorZ!

I have to admit, I'm not yet convinced that it's a good idea to use the QuasiText quasiquoter here. I can think of a few disadvantages:

1. It silently inserts a \n at the end of each line. While it's true that our code is wrapped to a width of 80 characters, this particular wrapping might not be appropriate for the user's view port. (Error messages can of course be viewed in different contexts: perhaps we should let the user's view port determine the wrapping?)

2. It doesn't play nicely with our 4-space indentation rule. If we do indent, then extra spaces are inserted in the resultant string. If we don't indent, then it breaks the nested structure of our code and makes the code harder to read (in my opinion).

3. It doesn't play nicely with syntax highlighting. Most Haskell syntax highlighters can highlight string literals in a different colour (e.g., bright red), but that won't work with this quasi-quoter. In fact, certain words such as "data", if included in the string, could mistakenly be highlighted as keywords. This makes it harder to visually differentiate strings from code.

Compare the following two snippets:

instance LiftHandler ErrCoinSelection where
    handler = \case
        ErrNotEnoughMoney utxo payment ->
            apiError err403 NotEnoughMoney [embed|
I can't accomodate such payment because there's not enough available UTxO in the
wallet. The total UTxO sums up to $(utxo) Lovelace, but I need $(payment)
Lovelace (fee included) in order to proceed with the payment.|]
        ErrUtxoNotEnoughFragmented nUtxo nOuts ->
            apiError err403 UtxoNotEnoughFragmented [embed|
There's a restriction in the way I can construct transactions: I do not re-use a
same UTxO for different outputs. Here, I only have $(nUtxo) available but there
are $(nOuts) outputs.|]
        ErrMaximumInputsReached n ->
            apiError err403 TransactionIsTooBig [embed|
I had to select as many as $(n) inputs to construct the requested transaction.
This would create a transaction that is too big and would be rejected by a core
node. Try sending a smaller amount.|]

with:

instance LiftHandler ErrCoinSelection where 
    handler = \case 
        ErrNotEnoughMoney utxo payment ->   
            apiError err403 NotEnoughMoney $ mconcat
                [ "I can't accommodate this payment because there's not enough "
                , "available UTxO in the wallet. The total UTxO sums up to "
                , toText utxo, " Lovelace, but I need ", toText payment 
                , " Lovelace (fee included) in order to proceed with the "  
                , "payment." ]  
        ErrUtxoNotEnoughFragmented nUtxo nOuts ->   
            apiError err403 UtxoNotEnoughFragmented $ mconcat   
                [ "There's a restriction in the way I can construct "   
                , "transactions: I do not re-use a same UTxO for different "
                , "outputs. Here, I only have ", toText nUtxo, " available but "
                , "there are ", toText nOuts, " outputs." ] 
        ErrMaximumInputsReached n ->
            apiError err403 TransactionIsTooBig $ mconcat   
                [ "I had to select as many as ", toText n, " inputs to "
                , "construct the requested transaction. This would create a "   
                , "transaction that is too big and would be rejected by a core "
                , "node. Try sending a smaller amount." ]

In the above pair of examples, there's not much difference in vertical space usage, but the latter has several advantages:

1. There are no \ns silently inserted.
2. It's indented according to the logical structure of the code.
3. Syntax highlighting works as normal.

Perhaps I'm missing something?

[jonathanknowles]

Hi @KtorZ

Regarding English usage, it seems that we have a mixture of two different styles:

1. Anthropomorphic style. Examples:
   • "I couldn't sign the given transaction"
   • "I can't adjust the given transaction"
2. Impersonal style. Examples:
   • "Couldn't sign the given transaction"
   • "The transaction could not be adjusted"

I think it would be best to pick one of these styles, and then use it consistently throughout our messages.

As for which style to choose: I would favour sticking to the impersonal style, as it seems more professional (and consistent with other tools that are out there).

What do you think?

[KtorZ]

Agreed with your first point. Note that the resulting messages don't contain any \n but that's because I am striping them away, which is more like a work-around. It'd be nice to have a quasiquoter that would discard indentation and newlines. Your proposition is also very sensible to me, I'll switch for a more vanilla-haskell with concat :)

About the tone, I have to say that I kinda like the impersonal style. That's also what the Elm compiler uses and I find it delightful while developing with Elm. It kinda avoid some friction with the system, but I suppose that's really educational / cultural here.

I 100% agree however about sticking to one style and be consistent with it.

[piotr-iohk]

I suppose: I didn't find or I haven't found

[KtorZ]

Fixed 👍

[piotr-iohk]

lgtm 👍 (except one small typo)

[jonathanknowles]

Agreed with your first point. Note that the resulting messages don't contain any \n but that's because I am striping them away, which is more like a work-around. It'd be nice to have a quasiquoter that would discard indentation and newlines. Your proposition is also very sensible to me, I'll switch for a more vanilla-haskell with concat :)

I just saw your updated commits! At least on my editor, it looks much much easier to read.

I agree it would be great to have a nicer quasi-quoter that does the Right Thing™ w.r.t. ignoring indentation and newlines. (Perhaps a minor side project for us when there's a quiet period?)

About the tone, I have to say that I kinda like the impersonal style.

Do you mean the anthropomorphic style, where the wallet refers to itself in the first person? (I have to admit that I just made up these terms, so feel free to suggest something better!)

That's also what the Elm compiler uses and I find it delightful while developing with Elm. It kinda avoid some friction with the system, but I suppose that's really educational / cultural here.

Interesting, I wasn't aware of that! I've just taken a look at the Compiler Errors for Humans essay. The error messages seem very nicely written, and consistent. Very convincing!

I 100% agree however about sticking to one style and be consistent with it.

💯

As per your original request, I'll take another look at the language content of the messages themselves.

[KtorZ]

Do you mean the anthropomorphic style, where the wallet refers to itself in the first person?

Whoops. That's what I meant indeed ^^" ...

Interesting, I wasn't aware of that! I've just taken a look at the Compiler Errors for Humans essay. The error messages seem very nicely written, and consistent.

And this was only the version 0.5 I believe. With 0.19, it's even better. I wish all compilers would be like that <3