messaging

messaging

[Arthur Schwarz]

In the following code fragment:

# include <ios>
# include <fstream>
# include <istream>

using namespace std;
void CommandLine(int argc, char** argv);
int main(int argc, char** argv) {
   CommandLine(argc, argv[]);
   ifstream x.open(argv[1], ios:in);
   ofstream y.open(argv[1], ios::in);
   
   return 0;
};

g++-4 messaging is:
>> g++-4 x.cpp
x.cpp: In function 'int main(int, char**)':
x.cpp:8: error: expected primary-expression before ']' token
x.cpp:10: error: expected primary-expression before ':' token

A recommendation and reason for change is:
1: x.cpp:8 error: illegal to pass an array without subscript value as an 
   argument
   The given message is accurate but non-expressive of the reason
   for failure.
3: cpp:10 error: illegal scope resolution operator ':'
   From memory, there are three uses of ':' in C++
   ':'   label terminator, <label>:
   ':'   case in a switch statement, case <value>:
   ':'   scope resolution operator, "::"
   The given diagnostic message is deceptive. 

art

Re: messaging

[Kai Henningsen]

Arthur Schwarz schrieb:
> In the following code fragment:
> 
> # include <ios>
> # include <fstream>
> # include <istream>
> 
> using namespace std;
> void CommandLine(int argc, char** argv);
> int main(int argc, char** argv) {
>    CommandLine(argc, argv[]);
>    ifstream x.open(argv[1], ios:in);
>    ofstream y.open(argv[1], ios::in);
>    
>    return 0;
> };
> 
> g++-4 messaging is:
>>> g++-4 x.cpp
> x.cpp: In function 'int main(int, char**)':
> x.cpp:8: error: expected primary-expression before ']' token
> x.cpp:10: error: expected primary-expression before ':' token
> 
> A recommendation and reason for change is:
> 1: x.cpp:8 error: illegal to pass an array without subscript value as an 
>    argument
>    The given message is accurate but non-expressive of the reason
>    for failure.

Actually, in this case I'd say that the original message is perfectly 
fine, and your suggestion is rather confusing. However, what one could 
say here is something like "[] is only allowed in declarations".


> 3: cpp:10 error: illegal scope resolution operator ':'
>    From memory, there are three uses of ':' in C++
>    ':'   label terminator, <label>:
>    ':'   case in a switch statement, case <value>:
>    ':'   scope resolution operator, "::"
>    The given diagnostic message is deceptive. 

Could perhaps say "':' is not a scope resolution operator", unless 
someone comes up with a use case where it is ...

Re: messaging

[Ian Lance Taylor]

Arthur Schwarz <aschwarz1309@verizon.net> writes:

> In the following code fragment:
>
> # include <ios>
> # include <fstream>
> # include <istream>
>
> using namespace std;
> void CommandLine(int argc, char** argv);
> int main(int argc, char** argv) {
>    CommandLine(argc, argv[]);
>    ifstream x.open(argv[1], ios:in);
>    ofstream y.open(argv[1], ios::in);
>    
>    return 0;
> };
>
> g++-4 messaging is:
>>> g++-4 x.cpp
> x.cpp: In function 'int main(int, char**)':
> x.cpp:8: error: expected primary-expression before ']' token
> x.cpp:10: error: expected primary-expression before ':' token
>
> A recommendation and reason for change is:
> 1: x.cpp:8 error: illegal to pass an array without subscript value as an 
>    argument
>    The given message is accurate but non-expressive of the reason
>    for failure.
> 3: cpp:10 error: illegal scope resolution operator ':'
>    From memory, there are three uses of ':' in C++
>    ':'   label terminator, <label>:
>    ':'   case in a switch statement, case <value>:
>    ':'   scope resolution operator, "::"
>    The given diagnostic message is deceptive. 


I filed http://gcc.gnu.org/PR39858 and http://gcc.gnu.org/PR39859 to
track these two issues and to make suggestions for how we can improve
them.  Thanks.

Ian

Re: messaging

[Arthur Schwarz]

The issues grow ever more complex. Suppose that we're dealing with macro's, some similarly named, and there's a typo. Suppose  several layers of template expansion are involved and nested deep within one there is some error. Suppose, suppose ... .

The motivation is not to expand the problem domain to the point were even stating the problem is a problem, but to creep up carefully and gradually on some consensus option as to what to do and then to go forward. All the points made are valid. At a certain time either the diagnostic message can not perceive nor report on the original cause of error, or the report is convoluted enough to be unreadable by all but the most diligent.

Let me address some general principles, which, of course, are both mine and may be wrong.
1: The purpose of compiler diagnostics is to present faults to a user
   in the most economic way possible.
2: The presentation should be a pointed as possible as to the detected
   fault.
3: The user should be required to understand as little as possible in
   order to understand the faulting message.

The details of specific messaging are not as important as the guidelines.

What I have seen in this thread and in a companion thread, messages, are these viewpoints.
1: The user should have some minimal capability to understand the 
   diagnostic messages as they are now.
2: The user is being overwhelmed with information and has difficulty
   sifting through it.
3: The messages show the fix but not the problem.

Clearly I am biased to 2: and 3:. But let me turn to 1; for a moment. 

In order to develop software in most languages, C++ being only one, it is not necessary to read nor understand the syntax equations for the language. The notion that developers should be compelled to acquire a knowledge of syntax equations won't work in practice. There is no authority to compell this knowledge nor to deny employment (or hobby work) for someone who doesn't have it. It might be nice but ... . So we are left with compiler users with minimal or none of the assumed pre-requisite knowledge.

The notion that these unknowledgeable users should be abandoned in provided diagnostic messages eventually translates into the compiler being abandoned by the users. In the small, probably fine. In the large I would think it unacceptable.

And there are competitive compilers. Some with better messaging and better messaging resources at the very point where g++ is weakest. You might argue that they are 'better in what way?', but I think the real argument is in what ways can these other products be a model for g++ to improve itself. Unless the notion is that g++ needs no improvement.

A reasoned attitude (I think) is to address each item without prejudice and see if there is some common ground, and then to proceed to see what is possible in general and what edge cases can't be simply solved. 

I think that there is a way to creep upon a general consensus which may not give everyone everything, but will give most something. And I believe the solution is not a 'camel by committee' but a more useable product. 

art

Re: messaging

[Manuel López-Ibáñez]

2009/4/14 Arthur Schwarz <aschwarz1309@verizon.net>:
>
> And there are competitive compilers. Some with better messaging and better messaging resources at the very point where g++ is weakest. You might argue that they are 'better in what way?', but I think the real argument is in what ways can these other products be a model for g++ to improve itself. Unless the notion is that g++ needs no improvement.
>

Then, you should mention what kind of error messages are given by
other compilers (or C++ front-ends). In my experience that helps a lot
to get your point across. Then, maintainers (who are the ones that at
the end decide what is accepted and what is not) can assess if the
alternative message is better or worse. But to do that, maintainers
will probably prefer a patch implementing the message.

GCC diagnostics need a lot of improvement. There are many open PRs
that are just waiting for someone to work on them. Sometimes someone
works on one of them, produces a patch, the patch gets accepted, the
PR gets fixed and GCC diagnostics are slightly improved.

> A reasoned attitude (I think) is to address each item without prejudice and see if there is some common ground, and then to proceed to see what is possible in general and what edge cases can't be simply solved.

And yet, you are arguing about "gcc messaging" in general. Without any
working knowledge of gcc capabilities or internals is just a pointless
exercise. You seem to assume that "someone" will implement your
proposals. That may happen, but in my experience, it is very, very
unlikely. What is more likely is that (a) some people will not
understand your verbal description of an implementation, (b) some
people are happy with things as they are and will resist change, (c)
some people will agree with you and do nothing else. In any case, the
result would be that nothing is done.

> I think that there is a way to creep upon a general consensus which may not give everyone everything, but will give most something. And I believe the solution is not a 'camel by committee' but a more useable product.
>

You do not need any consensus. You just need to put forward a patch
that implements your proposal and give enough reasons to the relevant
maintainers to accept your patch. And you'll need a lot of patience
and be willing to compromise. Otherwise, this thread has a 99% chance
of being completely futile (Reporting precise, well-argued and
detailed PRs will lower the chances).

Cheers,

Manuel.

Re: messaging

[Jonathan Wakely]

2009/4/14 Kai Henningsen:
> aschwarz1309@verizon.net schrieb:
>>
>> Thanks Kai. I do have what I hope is a more specific subjective reason for
>> saying that I think the existing diagnostics should be changed.
>> Fundamentally, what is provided in the messaging is not an indication of
>> what is wrong, but an indication of what is required to repair the fault. My
>> objections then become:
>> 1: As an old man full of wisdom, most developers can't distinguish a
>>   'primary-expression' from a washing machine. Further, to determine
>
> Well, here I think that such people should perhaps put down the keyboard and
> back away from using the compiler slowly. That's about the same as driving a
> car without knowing what a stop sign means.
>
> At least if they're unable to infer that a primary expression is a kind of
> expression, and there's no expression between [ and ].

Even if they are utterly flummoxed by the term, the message points
pretty clearly to the exact spot within the line that is wrong, as
does the ':' message.  In those cases it should be good enough to
point to the position that causes a problem, and a
reasonably-proficient c++ developer will spot the typo (not every time
- we can all be blind to simple typos sometimes, but that's not the
compiler's problem.)  I don't think  the compiler can be expected to
help if the developer doesn't know the language well enough to tell
that the syntax is invalid once pointed to the location of the error.

There are cases where the location in the diagnostic is (seemingly)
unrelated to the cause, but neither of your examples is in that
category.

...

> And really, I *like* it when the compiler uses terms directly from the
> language standard, instead of inventing some other terms.

Agreed.  I'd want an 'expert mode' with precise terminology if those
diagnostics were changed.

Jonathan

Re: messaging

[James Dennett]

On Tue, Apr 14, 2009 at 9:21 AM,  <aschwarz1309@verizon.net> wrote:
>
> Thanks Kai. I do have what I hope is a more specific subjective reason for saying that I think the existing diagnostics should be changed. Fundamentally, what is provided in the messaging is not an indication of what is wrong, but an indication of what is required to repair the fault. My objections then become:
> 1: As an old man full of wisdom, most developers can't distinguish a
>    'primary-expression' from a washing machine. Further, to determine
>    what correction might be needed most users would have to research
>    the C++ standard (or other standardized document supported by the
>    g++ development community) to find out exactly what constitutes a
>    'primary-expression'.

I believe that most developers manage to understand the message
sufficiently without needing (or caring) to know exactly what a
"primary-expression" is -- it's clearly some kind of expression, and
they already know what expressions are.  The additional information
provided by saying "primary-expression" is useful to those who do care
about it.  (And will motivate a few to become interested in the more
precise terminology, maybe.)

> 2: It puts an obligation on the g++ development community to ensure
>    that the messaging is consistent with documentation and that if the
>   term 'primary-expression' changes then g++ will change the messaging
>   to conform to the new term.

Being consistent with the terminology used by the C++ Standard is one
of the best ways to protect against changing terminology.  The
terminology in the standard does evolve, but generally very, very
slowly.

> 3: The cause of the error is more specific than it's solution. The cause
>    of the fault is the user (in this case me) provided something that
>    was wrong. It wasn't the lack of a 'primary-expression' but the
>    existence of the illegal constructs. My conjecture is that if the
>    message says "you did this wrong" then the user would have an easy
>    time of finding a fix.

I'm fairly sure that most g++ implementors are very happy when they
can, with reasonable confidence, suggest how to fix a problem.  The
difficulty is in doing so.  The correct fix is usually not obvious
based only on information available to the compiler, though in various
special cases it may be.  There are often many ways to eliminate an
error, one of more or which might have the correct semantics for a
given program.  Giving recommendations for how to *fix* the problem
can be counterproductive -- many programmers will happily do the first
thing they think of to make the warning/error go away, just as when
they blindly add casts to eliminate diagnostics about type errors.
Providing diagnostics that are simplistic is counterproductive.

I certainly agree that there is a lot of room for improvement in g++'s
diagnostics.  It's not a glamorous project, and it's far from easy,
but it would be valuable.  There may also be other ways to help: once
each diagnostic has a unique identifier, online documentation can
offer further advice on how to resolve issues, for example.

-- James

Re: messaging

[Kai Henningsen]

aschwarz1309@verizon.net schrieb:
> Thanks Kai. I do have what I hope is a more specific subjective reason for saying that I think the existing diagnostics should be changed. Fundamentally, what is provided in the messaging is not an indication of what is wrong, but an indication of what is required to repair the fault. My objections then become:
> 1: As an old man full of wisdom, most developers can't distinguish a
>    'primary-expression' from a washing machine. Further, to determine

Well, here I think that such people should perhaps put down the keyboard 
and back away from using the compiler slowly. That's about the same as 
driving a car without knowing what a stop sign means.

At least if they're unable to infer that a primary expression is a kind 
of expression, and there's no expression between [ and ].

>    what correction might be needed most users would have to research
>    the C++ standard (or other standardized document supported by the
>    g++ development community) to find out exactly what constitutes a
>    'primary-expression'. 

Let me put it like this: in this particular case, either it isn't 
particularly hard for the progammer to realise that he left out the 
index expression he wanted to write, or if that wasn't the mistake it 
demonstrates a rather fundamental misunderstanding of the language and 
he desperately needs to consult *something* to learn what he's been 
missing - no possible compiler message could close this hole in education.

> 2: It puts an obligation on the g++ development community to ensure
>    that the messaging is consistent with documentation and that if the 
>    term 'primary-expression' changes then g++ will change the messaging
>    to conform to the new term. 

It's directly from the language standard. If the standard changes 
(presumably for more reason than not liking the term), that place in the 
compiler needs changing anyway.

And really, I *like* it when the compiler uses terms directly from the 
language standard, instead of inventing some other terms. I can search 
for those terms in the standard, and most other people talking about the 
standard will use the same terms.

> 3: The cause of the error is more specific than it's solution. The cause
>    of the fault is the user (in this case me) provided something that
>    was wrong. It wasn't the lack of a 'primary-expression' but the
>    existence of the illegal constructs. My conjecture is that if the
>    message says "you did this wrong" then the user would have an easy
>    time of finding a fix.

It could well have been a typo for all the compiler knows, where you 
inadvertantly left out the index.

> I don't argue with the details of my wording. My intent is not to show that I am a better wordsmith but that the existing diagnostic messages are not specific enough. From Item 1: above, in order for the average user to fix the error the user must research the terms used, then compare the syntax given with the actual fault, and then fix the error. If the message say "this is the fault", the research goes the way of the woolly-mammoth.
> 
> The paradigm is that the message should provide the minimum amount of information required to identify the syntax/semantics which caused the failure.

And in this case, I believe that the original message does just that, 
whereas your proposal doesn't.

Re: messaging

[aschwarz1309]

Thanks Kai. I do have what I hope is a more specific subjective reason for saying that I think the existing diagnostics should be changed. Fundamentally, what is provided in the messaging is not an indication of what is wrong, but an indication of what is required to repair the fault. My objections then become:
1: As an old man full of wisdom, most developers can't distinguish a
   'primary-expression' from a washing machine. Further, to determine
   what correction might be needed most users would have to research
   the C++ standard (or other standardized document supported by the
   g++ development community) to find out exactly what constitutes a
   'primary-expression'. 
2: It puts an obligation on the g++ development community to ensure
   that the messaging is consistent with documentation and that if the 
   term 'primary-expression' changes then g++ will change the messaging
   to conform to the new term. 
3: The cause of the error is more specific than it's solution. The cause
   of the fault is the user (in this case me) provided something that
   was wrong. It wasn't the lack of a 'primary-expression' but the
   existence of the illegal constructs. My conjecture is that if the
   message says "you did this wrong" then the user would have an easy
   time of finding a fix.

I don't argue with the details of my wording. My intent is not to show that I am a better wordsmith but that the existing diagnostic messages are not specific enough. From Item 1: above, in order for the average user to fix the error the user must research the terms used, then compare the syntax given with the actual fault, and then fix the error. If the message say "this is the fault", the research goes the way of the woolly-mammoth.

The paradigm is that the message should provide the minimum amount of information required to identify the syntax/semantics which caused the failure.

art

--- On Mon, 4/13/09, Kai Henningsen <kai.extern@googlemail.com> wrote:

> From: Kai Henningsen <kai.extern@googlemail.com>
> Subject: Re: messaging
> To: "Arthur Schwarz" <aschwarz1309@verizon.net>
> Cc: gcc@gcc.gnu.org
> Date: Monday, April 13, 2009, 11:12 PM
> Arthur Schwarz schrieb:
> > In the following code fragment:
> > 
> > # include <ios>
> > # include <fstream>
> > # include <istream>
> > 
> > using namespace std;
> > void CommandLine(int argc, char** argv);
> > int main(int argc, char** argv) {
> >    CommandLine(argc, argv[]);
> >    ifstream x.open(argv[1], ios:in);
> >    ofstream y.open(argv[1], ios::in);
> >       return 0;
> > };
> > 
> > g++-4 messaging is:
> >>> g++-4 x.cpp
> > x.cpp: In function 'int main(int, char**)':
> > x.cpp:8: error: expected primary-expression before ']'
> token
> > x.cpp:10: error: expected primary-expression before
> ':' token
> > 
> > A recommendation and reason for change is:
> > 1: x.cpp:8 error: illegal to pass an array without
> subscript value as an    argument
> >    The given message is accurate but
> non-expressive of the reason
> >    for failure.
> 
> Actually, in this case I'd say that the original message is
> perfectly fine, and your suggestion is rather confusing.
> However, what one could say here is something like "[] is
> only allowed in declarations".
> 
> 
> > 3: cpp:10 error: illegal scope resolution operator
> ':'
> >    From memory, there are three uses of ':'
> in C++
> >    ':'   label terminator,
> <label>:
> >    ':'   case in a switch
> statement, case <value>:
> >    ':'   scope resolution
> operator, "::"
> >    The given diagnostic message is
> deceptive. 
> 
> Could perhaps say "':' is not a scope resolution operator",
> unless someone comes up with a use case where it is ...
>