value of documenting error messages?

[Richard Eisenberg]

I'm in favor of short, undescriptive, quite-possibly numeric error codes.

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 somewhere what the next error code should be, without having to search the codebase for a use.
* 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.
* Short.
* 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.

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.

> 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.

-------

Surfacing up a few levels: it sounds like a good next step is not to get all these constructors finely documented, but instead to come up with a way to connect these constructors to user-facing documentation. This might be done by slurping out Markdown from the GHC source code, or perhaps something better. It would be a shame to invest a lot of effort in documenting the constructors in a way that serves only GHC developers, not end users, when we can perhaps do both at the same time.

Thanks,
Richard
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/ghc-devs/attachments/20210602/5ce5bbfa/attachment.html>