Designing Better Compiler Diagnostics — Lessons from building Klar

Source: Dev.to

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?

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

Source that produced it (.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.
• Layout: short summary → precise location (file:line:col + caret) → human explanation → actionable fix.
• Avoid playful/friendly language; prioritize clarity and predictability.
• Suggestions should be conservative—e.g., “did you mean X?” only when 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)