RFR: Updated section on Code Conventions.

[Stuart Marks]

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 
Documentation. [1]

(Not Stack Overflow the main Q&A site, which seems reasonably successful as a 
crowdsourced Q&A site.)

Stack Overflow Documentation [2] 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 [3]. 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. [4] 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 
everybody's time.

s'marks


[1] https://stackoverflow.com/documentation

[2] 
https://meta.stackoverflow.com/questions/303865/warlords-of-documentation-a-proposed-expansion-of-stack-overflow

[3] https://meta.stackoverflow.com/questions/354217/sunsetting-documentation

[4] https://riptutorial.com/java/topic/90/collections