value of documenting error messages?

[Tom Ellis]

On Wed, Jun 02, 2021 at 06:13:17PM +0000, Richard Eisenberg wrote:
> I'm in favor of short, undescriptive, quite-possibly numeric error
> codes.

These responses are so completely opposite to what I expected that I
can't help thinking I've made a fundamental error in my understanding
of what we're trying to achieve!  Since no one has suggested any
support for the idea of descriptive error codes I'm pressing on mostly
in the hope that someone will be able to see from where my
misunderstanding arises and set me straight.

Before I continue, I'd like to suggest that this is very much a
user-facing issue and I would be strongly in favour of actually asking
users about what they prefer (and allowing them to discuss for a
while) rather than taking a straw poll amongst GHC developers.

To that end, would it be inappropriate of me to link this discussion
to Haskell Reddit and/or Haskell Discourse?

> Advantages:

> Easy to sequentialize. We might have, for example, a
> "conflicting_trait_implementations" from this year, move on from
> that design, and then accidentally reintroduce it in a decade, to
> confusion. Along similar lines, it is easy to write in a comment
> somewherewhat the next error code should be, without having to
> search the codebase for a use.

I don't understand at all why it's valuable to sequentialize.  Is the
relative ordering of error codes meaningful in some way?

I don't see why deprecating an error code and reintroducing it is a
problem any more than doing the same to a function or GHC extension.

If we are *really* desperate to disambiguate then
conflicting_trait_implementations_2021 still seems better to me than
E195.

> Easy to make compositional. We can choose to have all GHC error
> codes begin with G (for GHC). Then Cabal could use C, Haddock could
> use H, and Stack could use S. This makes it easy for users to tell
> (once they've learned the scheme) where an error has come from.

Surely the same holds for descriptive error codes.  One could have
G_conflicting_trait_implementations, H_malformatted_section_header,
...

> Short.

Again I must be misunderstanding.  Why is brevity valuable?  Aren't we
expecting users to read these things and look them up?  Copy/paste is
free.

> No chance for misspellings during transcription. When I'm copying a
> terse identifier, I know I have to get every glyph correct. If I
> remember that the error code is "bad_generalizing", I might not know
> how "generalizing" is spelled. I might also forget whether it's
> "generalizing" or "generalization". And I could very easily see
> myself making either both of these mistakes as I'm switching from
> one window to another, in under a second.

Surely it's just as easy to mistype E159 as E195 as it is to misspell
"generalise".  As above, copy/paste is free and if we *really* want to
be helpful then instead of naked error codes we should give URLs whch
directly link to sections in the GHC users guide (or other appropriate
resource).

> Disadvantages:

> The code does not impart semantic meaning. But I argue this is not
> so bad, as even a more descriptive code does not impart a precise
> enough semantic meaning to be helpful.

I challenge you to name your next GHC extension X25!

> > On Jun 2, 2021, at 1:49 PM, Tom Ellis
> > <tom-lists-haskell-cafe-2017 at jaguarpaw.co.uk> wrote:
> >
> > If we really think that non-descriptive codes are the clearest way
> > to communicate between machines and humans then I wonder if we
> > should rename `mapAccumL` to `F392` and `TypeFamilies` to `X56`.
>
> I think this is a false equivalence. The error codes are meant to be
> looked up when you see them on your screen, not remembered and then
> produced at will.

Possibly ... possibly not.

"Hey Anna, what should I do about E159?"

"Hey Anna, what should I do about conflicting_trait_implementations?"

Which would I prefer to shout to my colleague across the room?


To me this seems like a rare opportunity to do something where people
will say "Hey look, that formidable Haskell compiler is doing
something that's friendlier than the equivalent in any other
compiler!".  For such an important user-facing feature I don't
understand why we're not asking users what they prefer.

Where could I be going wrong in my understanding?

Tom