RFR: Updated section on Code Conventions.
stuart.marks at oracle.com
Thu Jul 2 21:56:10 UTC 2020
On 7/2/20 6:40 AM, Magnus Ihse Bursie wrote:
> I thought, or at least hoped (perhaps naively), that we had, as an
> organization, finally learned that being a bit more agile -- without
> compromising on our high standard of quality -- had done wonders for our
> project. That 6-month releases was a boon sine qua non. That doing things
> mostly right, releasing them, and then adjusting them based on feedback, was
> vastly superior to doing nothing in fear of not doing it perfect from the start.
> But this view collides heavily with Mark's that we, before we even start
> considering what a Style Guide should contain, must have one of our most
> experienced developers signing up to be the sole editor for a substantial
> period of time. With that premise, we can be quite sure that we will never get
> a Style Guide. If this is indeed the expected and preferred outcome for the
> proponents of this line, I think it borders on dishonesty: if so, please say
> that you do not *want* a style guide for OpenJDK. And if you do want a style
> guide, can you with a straight face say that it is likely that we will ever
> get one with that kind of requirements? We have waited for years, and years
> for that kind of perfection, but with nothing to show. What will be different
> in the coming five years?
Well there's rather a lot to unpack here.
It's certainly been frustrating that the 2o-year-old /Code Conventions/ hasn't
been updated. Andreas Lundblad made a credible attempt to do so, now five years
ago, and I don't know why that stalled out. (Nor do I want to relitigate the
issues that led to the effort stalling out.)
It seems like adding the style guide to the Developer's Guide offers a path
forward. Doing that allows everybody to work on it. We can make quick progress
on it after that, right? This is surely better than what we have now (nothing),
because the best is the enemy of the good, right?
In my estimation, doing this will lead to a "crowdsourcing" of the effort, and
this will leave us in a /worse/ position than we're in today. (Believe it or not.)
As an example of where crowdsourcing fails, I'll point to Stack Overflow
(Not Stack Overflow the main Q&A site, which seems reasonably successful as a
crowdsourced Q&A site.)
Stack Overflow Documentation  was an effort to crowdsource fixing the
"documentation problem." Documentation does seem to be a general problem in the
industry, and certainly Java has its share of documentation problems. Stack
Overflow Documentation was launched and then shut down perhaps a year later; the
explanation is given in . That explanation offers mostly a business rationale
for shutting it down: lack of growth in number of users, inability to generate
revenue for Stack Overflow the company, and so forth. Quite reasonable. But
little has been said about the /quality/ of documentation produced by the Stack
Overflow Documentation project.
The SO Documentation materials are all CC BY-SA. The company made an archive of
that data available, and it's been re-hosted elsewhere so that it's possible to
look at it. For example, take a look at the Collections topic of the Java
documentation category.  I spent a few minutes with it, and *frankly, it is
just terrible.* It was this way when the SO Documentation project was active.
Back then I had looked at it for about five minutes, and I quickly decided that
it was *beyond repair*.
There are so many problems, it's hard to know where to start. Fundamentally I
think the choice of topics is bad and they are organized poorly. Apparently no
thought was given to what topics are important or what order to cover them in.
It's not even clear what audience the material is intended for. (These issues
are certainly related.) It's random train-of-thought as far as I can tell. It
suffers from an utter lack of cohesion. Stack Overflow Documentation is this way
/because/ it's a crowdsourced effort.
Surely the Style Guide couldn't get this bad. After all, we'll use Andreas
Lundblad's draft as a starting point. It seems to be pretty cohesive already, so
it wouldn't get as bad as SO Documentation, right? Well I'm not confident about
that. It takes positive effort to keep something in good shape. In the absence
of a central editor, a few small changes here and there by a few different
individuals will quickly give rise to internal contradictions and other
inconsistencies. These will soon damage the credibility of the entire document.
You know how quickly bit-rot sets in when software isn't maintained? Well, it's
the same way with documents.
Where does that leave us? I agree with the desire to move forward quickly. I
don't think Mark's (or my) approach of having a central editorial authority
necessarily implies slow progress. However, people who are willing and able to
do that are in short supply, and finding those people could take (and has taken)
a long time.
I see the temptation to just check it in and let people work on it. It seems
like that would allow for lots of progress. But that's a mirage. It will just
lead to chaos and disorganization and it will eventually end up being a waste of
More information about the jdk-dev