Re: Open issue: error codes

Steven Pemberton <steven.pemberton@cwi.nl> writes:
> I find that all the proposals make the spec less readable. These error
> codes are for implementers, not users of the language,

I think that’s completely backwards. The error codes are absolutely not
for the implementors. Heck, they’re an inconvenience for the
implementors. It would be much easier as an implementor to spit out any
error message I felt like writing for any random condition I happened to
notice.

Error codes are for users. They’re the foothold in the spec that let’s
them figure out what

  Error: S123 Cannot preambulate the nonterminal while the fizz is buzz.

means. They can go find S123 in the spec and work out what they’ve done
wrong. They don’t have to pattern match from the error message back into
the part of the spec they think maybe, that message could be about. They
don’t have to build a mental correspondence between the error messages
they get in my implementation, or the Spanish translation of those error
messages, with the messages they get from your implementation or someone
else’s.

They are also a mechanism which allows users to judge, and demand,
interoperability from implementations because to pass the test suite,
implementors will have to generate the right error codes at the right
times.

> and consequently make the spec less approachable. 

I’m wholly in favor of approachable specifications, but specifications
are not novels. They are specifications of the precise technical details
of a complicated and intricate system which has an array of moving parts
and can go wrong in many, sometimes unexpected, ways.

> So my proposal is that
> we do it the other way round: an appendix listing all errors, with
> links from there to the paragraph where they originate.

If that’s the best we can get consensus on, I suppose it’s better than
nothing.

> I also dislike the "s001" style of numbering, since it suggests that
> there are going to be hundreds of them. "s1" conveys the same
> information.

If you’d prefer “S01” to “S001”, fine, I suppose. You seem confident
that we’ll never need more than 99 of them. If Invisible XML succeeds
and grows, I bet that will turn out to be wrong, but we can burn that
bridge when we get to it, I suppose.

However, there are already more than nine of them and I think there’s
value in having them be fixed width. It helps users identify them and it
means they line up better in tables and lists.

I’d probably be happy with three digit random numbers, if you’d prefer,
there’s certainly, explicitly nothing significant about the numbers or
their order.

The other approach is codes, but making short codes that are less
usefully cryptic than numbers is hard and we then have to argue about
every single code. Is SNSUCAT better than S01? *shrug* Maybe.

                                        Be seeing you,
                                          norm

--
Norm Tovey-Walsh
Saxonica