[swift-dev] RFC: Better diagnostics through simplification

[John McCall]

> On Aug 24, 2017, at 10:41 AM, David Zarzycki <zarzycki at icloud.com> wrote:
>> On Aug 24, 2017, at 00:08, John McCall <rjmccall at apple.com <mailto:rjmccall at apple.com>> wrote:
>> 
>>> 
>>> What do people think? The meat of the change is tiny and below. The vast majority of the work is the long and painful fallout in the test suite, which I’m cautiously (and perhaps foolishly) stepping up to doing.
>> 
>> I think that’s an interesting improvement in this specific message, but it's not obvious that it would be an improvement to all messages.
> 
> Hi John,
> 
> That is certainly true. I’ve already seen that after a few rounds of testing this and watching the changing output from the test suite. That’s why I emailed this list before getting too deep into this change. In general, I thought the output was better than before, but reasonable people might disagree. The only place where I felt the extra verbosity was clearly distracting was/is the ‘where’ clause diagnostics.
> 
>> Generally the way we did things like this in Clang was to add a modifier to the diagnostic string, so that it would look something like "%type1", which would be understood to expand to a noun appropriate for the type.  That way, it was easy to take advantage of it for a specific diagnostic, but you weren't forced into it by default.  I think that’s still the right approach here.
> 
> 
> Interesting. Good to know. Setting aside what the default should be, and unless I’m missing something, the clang style “%type1” approach has the same underlying challenges as this patch:
> The verbosity snowballs because the goal of printing the inner decl kind is complicated by having layered type qualifiers (optional, metatype, etc).
> Having two very different approaches to printing a type during diagnostics is lame (i.e. dense native syntax versus verbose English descriptions).
> Maybe the “right” approach – and I’m only half serious about this – is to have a way for the compiler to print ‘(/*struct*/Foo).Type?’. Is it ugly? Arguably. Is it dense? Yes. Does it snowball? No. Does it scale? Absolutely! For example, consider a nontrivial “optional dictionary of tuple” type. It might look like this: ‘[/*struct*/String : (/*class*/Foo, /*enum*/Bar)]?’. If knowing the decl kind is helpful, then the latter output is a huge improvement.
> 
> For whatever it may be worth, I’m not wed to this proposal. The motivation behind this patch was preparation for the eventual day when a new nominal type is created (like Chris’s “actor” proposal or something else). I could certainly narrow the scope of this work to rewording some of the diagnostics to be more decl kind agnostic. For example: “subclass” becomes “subtype”, “superclass type” becomes “inherited type”, etc. If people are open to that, I can narrow the focus of this work.

I think making it easy to have a better noun than "type" before a type in a diagnostic is valuable, but yeah, I think you need to:
  - take it as a mission to not use more than two words as an introducer
  - be cool with falling back to "type" if you're not sure what else to say
  - think carefully about whether using a more specific noun than "type" is really providing any non-obvious information

For example, "type" is probably fine to introduce function types, because it's usually visually obvious that a type is a function type.  On the other hand, you could consider using a more precise noun in the same sort of situations where you might print an aka clause, e.g.:
  can't frobonicate with function type 'HappyCallback' (aka '(HappyContext) -> ()')

Finally, of course, it's okay just to make incremental improvements instead of trying to make everything perfect all at once. :)

John.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-dev/attachments/20170826/11ca6eb6/attachment.html>