Lately, I've been thinking about how the diagnostics user experience for Swift could be improved in the long term. I thought it would be valuable to start a conversation around what kind of improvements people would like to see and what we can learn from other compilers, maybe resulting in some kind of rough roadmap if there's enough interest.
Note: when I refer to diagnostics UX, I'm referring more to how diagnostics are structured and presented to the user as opposed to how they are generated (for example, through the new type checker diagnostics framework).
What follows are some miscellaneous ideas for possible improvements. When evaluating these, I think it's worth considering both how they fit with the motivations of the existing diagnostics style, and how high impact they are relative to the effort required to implement. I look forward to hearing everyone's opinions on this and other ideas you have to improve this part of the compiler!
Extended Diagnostic Messages (inspired by Rust): Rust has a feature which lets the user run
rustc --explainfollowed by an error code to view a more detailed description of the error. These messages include a more detailed description, minimal examples of broken and fixed code, suggestions for how to fix the issue, and additional information about relevant related concepts. These can be very helpful for beginners to the language or more experienced users encountering a new error for the first time. For example, the error
protocol 'P' can only be used as a generic constraint because it has Self or associated type requirements, which currently appears in over 200 stack overflow questions, might benefit from a longer explanation which wouldn't fit in a traditional Swift diagnostic. They also fit nicely with the idea of progressive disclosure. However, adopting a feature like this would require a large effort.
- Compiler error index: Closely related to the above, Rust has an online error index which can be a useful reference when looking up an unfamiliar error.
- Changes to output formatting: Both Rust and Elm make some interesting choices when formatting error output that we might be able to learn from. These include easier to parse line numbering and tying notes more closely to the parent error/warning. For example, this code:
let y = 0 var y = 0
hello.swift:2:5: error: invalid redeclaration of 'y' var y = 0 ^ hello.swift:1:5: note: 'y' previously declared here let y = 0 ^
But might be easier to read if it was formatted as:
hello.swift:2:5: error: invalid redeclaration of 'y' 1| let y = 0 | ^ note: 'y' previously declared here 2| var y = 0 ^
Syntax highlighting code excerpts might be valuable as well when color diagnostics are enabled.