JDK-6397027 likely doesn't have a satisfying solution

[Ethan McCue]

Following advice from Vicente, ~3 weeks ago I started to look at
JDK-6397027.

"Some messages begin with capital letters; others do not. We should decide
which is right and fix the rest."

The issue as stated seems to just be one of consistency. There are some
messages which begin with capital letters and others do not. So to start I
tried to figure out who the winner should be.

When an error message is a single sentence on a single line it is the
overwhelming "consensus of the corpus" that it starts with a lower-case
letter.

A few examples

compiler.err.wrong.receiver
wrong receiver parameter name

compiler.err.initializer.not.allowed
initializers not allowed in interfaces

compiler.err.cant.inherit.from.anon
cannot inherit from anonymous class


There are some error messages which obviously break this convention and
could be put more in line.

compiler.err.bad.functional.intf.anno
Unexpected @FunctionalInterface annotation

compiler.err.proc.no.service
A ServiceLoader was not usable and is required for annotation processing.

compiler.err.no.java.lang
Unable to find package java.lang in platform classes

But after mulling it over, I don't think the solution is as clear cut as
performing find-and-replace on all leading capital letters.

---

I started my analysis by going through all 90 messages
in compiler.properties and marking the ones that felt like "obvious"
candidates to change to start lower case. Of these 38 did not feel clear
cut, so I went back through to try to find a way to articulate why.

Capitals seem to most necessary as a mechanism for making grammar "flow" if
we have

* Messages that go on multiple lines.

compiler.err.icls.cant.have.static.decl
Illegal static declaration in inner class {0} modifier ''static'' is only
allowed in constant variable declarations
* Messages which have multiple distinct clauses

compiler.err.option.removed.source Source option {0} is no longer
supported. Use {1} or later.
compiler.err.proc.cant.create.loader
Could not create class loader for annotation processors: {0}
compiler.note.compressed.diags
Some messages have been simplified; recompile with -Xdiags:verbose to get
full output

* Messages which will be composed into one of the above

compiler.note.removal.recompile
Recompile with -Xlint:removal for details.

* Consistency with a variant which does one of the above.

compiler.err.bad.functional.intf.anno
Unexpected @FunctionalInterface annotation

compiler.err.bad.functional.intf.anno.1
Unexpected @FunctionalInterface annotation {0}
---

I broke up the categories of information that existing error messages
convey as follows.

* where - What area of the code was incorrect
* what - The thing that was wrong about the code
* why - Why that thing that was wrong was wrong
* hint - How the user might remedy this error

I then made a spreadsheet here where I manually filled in my read on that
information

https://docs.google.com/spreadsheets/d/149dqMEODacRQrjA4mrjh-4quN_vFw0yF5SIPslefiCc/edit?usp=sharing

And with that framing, it seems most "legitimate" use of capitals is in an
attempt to encode more information that just "what" went wrong. Most often
the culprit is a message trying to present a "hint" to the user, but
sometimes it is just that the "what", "why" or "where" does not fit
naturally into a single sentence.

And at this point I think I've opened a can of worms, because there are
quite a few other errors in the corpus which break the "single statement"
rule for good reason, and with different solutions.

compiler.err.foreach.not.applicable.to.type
for-each not applicable to expression type required: {1} found: {0}

compiler.err.preview.not.latest
invalid source release {0} with --enable-preview\n(preview language
features are only supported for release {1})
What I think this means is that there is no easy way to make the error
messages "consistent" within the current framework without either stripping
useful info from the offenders or adopting some output style which doesn't
need to bend to support hints.

---

I am at least partially conscious that the "right" solution here - the one
that ends with the JDK having consistent, helpful, and informative error
messages - is a JEP level effort. I haven't proven yet that I'm tall enough
to ride that ride, but I hope articulating this can move the needle some.

Caveats
* There is probably an unhealthy dose of confirmation bias on my part.
Error messages are my White Whale and "why can't they just be like rust"
crosses my mind a bit too often.
* I mostly looked directly at what was in the compiler.properties files so
I don't have a totally complete picture of how some of the smaller messages
are glued together.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/compiler-dev/attachments/20220224/9bbbebf3/attachment.htm>