Re: Question about base types

[dewar@merv.cs.nyu.edu (Robert Dewar)]

Matthew Heany said (replying to me)

<<>which is I think clear to people (at least no one ever asked for an
>explanation of this message).

I think it's ambiguous.  Do you mean a first named subtype, or non-first
named subtype?

>
>More accurate would be to say
>
>  "rep clause may only be given for first named subtype"
>
>but this seems more confusing to us.

Disagree.  That is the message I would *expect* to see.>>

Robert replies:

Right, this is a quite typical reaction. In my experience, the biggest
enemy of good error messages from compilers is people who know too much,
and want the error messages to be technically correct at the level at
which they understand the language.

Matthew you don't *really* think this is ambiguous, in the sense that you
think it would confuse you surely -- since surely you know the language
well enough that you (a) know the rule involved anyway, and (b) you
understand the terminology issue to understand what GNAT means here.
Note that I am not just guessing that this message is clear, my metric
for concern about messages being unclear is a very simple one, I look
to see if anyone ever sends mail saying "what does this mean, I don't
understand".

Error messages should be designed to help people who do NOT know the rule
involved, and threfore, sort of by definition, are NOT experts in the
language. The phrase "first named subtype" is not likely to be in the
vocabulary of beginners, and you often simply confuse people by using
aggressively correct terminology.

Let me give some other examples:

I much prefer the message

  "generic package not allowed here"

Rather than 

  "package name required here"

Eveyrone knows a generic package is not a package, right? wrong!

Another example, I would always use the term package spec in an error
message, rather than package declaration, since in practice the latter,
term, though correct is not familiar.

Going back to types and subtypes, it seems obvious to any beginning
Ada programmer (and to a lot of not so beginning programmers) that

  type x is ....   introduces a type name

and

  subtype x is ...  introduces a subtype name

Yes, of course, we experts know that this is wrong, and can have fun 
scoffing at the uneducated hoi polloi who don't understand, but error
messages are meant to help people find their errors, NOT send people
somewhere else for help so that they can be educated on proper Ada
terminology.

Of course the best of both worlds would be to have the capability of
further explaining messages in extended text, where it might in some
cases be appropriate to explain the more precise terminology, and
even give an RM reference. As I have mentioned previously, this is a
tool that is on our list of useful things to do.

Meanwhile, my main useful input on error messages continues to be
mail from people who have genuinely found an error message that
confused them in a program they wrote themselves. The error messages
in GNAT have been constantly tuned against such input. I gave an
example in my previous message, a second semester Ada student (so
not someone who was a complete beginner) sent a message to me
with the fragment:

     1. procedure q is
     2.   x : q;
              |
        >>> subtype mark required in this context

     3. begin
     4.    null;
     5. end;

And could not understand the message. That's because the word subtype
set him thinking in the wrong direction. The real error was that he
had accidentally hidden his type name, but the word subtype got him
thinking "why should I need a subtype here, I don't see why a type
is not allowed?"

I also think the word "mark" is gratuitous here, and my inclination is
to change the message to read

  >>> type or subtype name required in this context

and in practice I think that would reduce the number of people who got
blocked by this message.

Remember, I never care about the expert who looks at a message, knows
what's wrong immediately, and thinks to themselves "that message is not
quite right". I worry only about avoiding people reading a message and
being puzzled and not being able to figure out how to fix their code
because the message is not sufficiently clear to them.

It's a definite philosophy which is certainly different from say the
inclination to give RM references on all messages. In GNAT we very
occasionally do give RM references if (a) there is a subtle rule that
cannot be summarized in one and (b) the rule in the RM is reasonably
clearly stated and accessible. For example:

     1. with System; use System;
     2. procedure q is
     3.   x : address;
     4.   y : String (1 .. 5) := "hello";
     5.   for y'Address use x;
                            |
        >>> invalid address clause for initialized object "y"
        >>> reference to variable "x" not allowed (RM 13.1(22))

     6. begin
     7.    null;
     8. end;

but that is definitely an exception.

Everyone can help improve error messages in GNAT (although I must admit
I will generally pay more attention to beginning students here than to
experts on CLA :-). If you really *do* find an error message that puzzles
you and you can't figure out the error, and think that an error message
change would help, send the comment along to report@gnat.com. On the
other hand, if your objection is a tecnical objection from an expert,
and you really knew what was wrong anyway, that's not such critical input.

Robert Dewar
Ada Core Technologies