Designing Better Compiler Diagnostics — Lessons from building Klar

I’m building a small experimental language called Klar (formerly Klang) as a way to explore explicit semantics, strict diagnostics, and polyglot tooling. This is not a production-ready language — it’s a design exercise — but along the way I’ve been obsessing over one concrete problem: what makes a compiler error actually useful?

Below is a real example of how Klar currently reports an unresolved symbol error (trimmed for brevity). I’d love feedback on whether this format is too verbose, just right, or missing something important.

Example diagnostic (what the user sees):

[K:E217] UnresolvedSymbol
ERROR (SEMANTIC)
at undefinedVariableExceptionTest.kl:10:12

 8 |     }
 9 |
10 |     println(total);
   |             ^

Cause:
  The variable 'total' does not exist

Fix:
  Remove it or create it

The source that produced it (Klar .kl):

@Use("java")
public void main(){
    integer count = 10;
    integer iterator = 0;

    while (iterator < count){
        iterator = iterator + 1;
    }

    println(total);

    return null;
}

Design notes (short):

Diagnostics are structured as data first (error code + metadata) and rendered as readable text.

Short summary → precise location (file:line:col + caret) → human explanation → actionable fix.

I aim to avoid playful/friendly language in favor of clarity and predictability.

Suggestions should be conservative — “did you mean X?” only when the confidence is reasonable.

Questions for the community

When you evaluate a diagnostic, what matters most: precision, minimalism, or actionable fixes?

Do you prefer a single-line summary first (then details) or a single readable paragraph?

Are there diagnostic patterns you’ve seen that consistently confuse users?

I’m specifically interested in how diagnostics trade off between noise and helpfulness. If you want to see more examples (type mismatches, missing returns, magic-number warnings), I’ll paste them in the comments.

— ~K' (building Klar)