State of the Java Style Guidelines document

[Lars Francke]

Thanks for the feedback everyone!

I understand that people have different personal preferences various topics
and we'll never be able to find one style that accommodates all of them.

Just to explain what my personal motivation for this push is:
Lots of open-source projects (I'm mostly working with the Big Data Apache
projects) list the old Sun Code Conventions[1] as the code style to follow.
Unfortunately those haven't been updated in 20 years and they leave out
lots of minor details that have been clarified in the new version. So for
me a revised version of this old document (with no/little changes in the
actual code style) would already be a huge benefit.

I'm not lobbying for these style guidelines to be adopted by every OpenJDK
project (or any project in fact). I'd love for those guidelines to be
published as-is as "guidelines" that projects (outside of the OpenJDK as
well) can adopt. Nothing's stopping you (as is done in Apache projects
frequently) to have your own guidelines "inherit" from these and overwrite
certain rules.

> I'm sorry, I can't bring myself to reduce the readability of my code
because the one person in charge had something against a single additional
line in the source base that would provide clarity...

People obviously have different opinions on readability and I'm not sure if
it's a good idea to list alternative versions for all contentious issues
because it would make the whole document more or less meaningless. I think
Jonathan has a good point in that the guidelines already cater for
differing styles and you could publish your own version for the FX project
that lists the points where you deviate from these guidelines.

A more procedural question though: Assuming we can find a document version
that we all agree on. What would be needed to publish it and who'd be the
right person to do so?

Thank you,
Lars

[1] <http://www.oracle.com/technetwork/java/codeconvtoc-136057.html>

On Wed, Jul 26, 2017 at 9:46 PM, Jim Graham <james.graham at oracle.com> wrote:

> Agreed, but this version is already in use in the code and was adopted by
> an entire group, though not the group that the effort towards updating this
> document was based in.
>
> I had suggested it to the author.  It seemed to go nowhere and I don't
> believe it was presented in a poll that was sent out asking for feedback on
> style variations so it never got the visibility I think it deserved.  There
> were clear biases to ignore the input at the time and I thought it
> short-sighted.
>
> There are many areas where I disagree with the variant chosen, but will go
> with the flow, but this is one area where I really don't get why the
> suggestion was ignored as I see it as superior in terms of maintainability
> on every single front to what was documented - to the extent where I will
> always be non-compliant with the suggested form - I'm sorry, I can't bring
> myself to reduce the readability of my code because the one person in
> charge had something against a single additional line in the source base
> that would provide clarity...
>
>                                 ...jim
>
>
> On 7/26/17 12:30 PM, Jonathan Gibbons wrote:
>
>> Religious wars are waged over lesser issues.
>>
>> I think it is presumptious to recommend a style for all Java code, but I
>> do think it is reasonable to establish coding guidelines for a specific
>> code base, such as OpenJDK.  Even so, opinions will still differ, and there
>> was an attempt in Andreas' work to accommodate reasonable alternatives,
>> with a general proviso of, "when editing existing code that has a
>> consistent style, try to conform to that style, and not slavishly conform
>> to some different standard."
>>
>> -- Jon
>>
>>
>> On 07/26/2017 12:21 PM, Jim Graham wrote:
>>
>>> Sorry to sound like a broken record here - I think it should be
>>> published too, but... ;)
>>>
>>> If only it would adopt the convention used in much of 2D and FX of
>>> putting a brace on its own line after a line-wrapped conditional/method
>>> declaration (preferably as the primary form, but even as an acceptable
>>> alternative):
>>>
>>> public void longMethodNameUsedOnlyForIllustration(SomeLongClassName
>>> paramA,
>>>                                                   LongClassName paramB,
>>>                                                   int someOtherParam)
>>>         throws OtherFormsAreUglySmileyFaceException
>>> {
>>>     ...
>>> }
>>>
>>> provides the cleanest and clearest sight line to see where the body of
>>> the method/class/conditional starts...
>>>
>>> </broken record mode>
>>>
>>>                 ...jim
>>>
>>> On 7/26/17 3:21 AM, Remi Forax wrote:
>>>
>>>> I agree with Lars,
>>>> this should be published ASAP.
>>>>
>>>> regards,
>>>> Remi
>>>>
>>>>
>>>>
>>>>
>>>> On July 26, 2017 8:41:29 AM GMT+02:00, Lars Francke <
>>>> lars.francke at gmail.com> wrote:
>>>>
>>>>> Hi everyone,
>>>>>
>>>>> I've been following the work Andreas Lundblad has done on the new Java
>>>>> Style Guidelines[1]. I know that he's not with Oracle anymore but the
>>>>> draft
>>>>> looks good (and has done so for at least a year), I think all comments
>>>>> have
>>>>> been worked into it. Why has it not been published? Is anyone working
>>>>> on
>>>>> this, if yes, who?
>>>>>
>>>>> I'd be happy to do any work needed to bring it to a final and published
>>>>> form if needed. But to me it looks ready to be published today (apart
>>>>> from
>>>>> a few minor issues I've reported to Andreas already).
>>>>>
>>>>> The old code conventions from 1997 can really use an updated version.
>>>>>
>>>>> Cheers,
>>>>> Lars
>>>>>
>>>>>
>>>>> [1] <http://cr.openjdk.java.net/~alundblad/styleguide/index-v6.html>
>>>>>
>>>>
>>>>
>>