State of the Java Style Guidelines document

[Mike Duigou]

I would be very disappointed if the Guidelines were finalized and 
published in their current form. While a noble and necessary effort I 
believe the proposal still tries to formalize too much and admits too 
much personal preference. Draft V6 is big improvement over V5 in that it 
provides more flexibility by removing many of the V5 recommendations. 
It's disappointing that the entire V5 comments were not disclosed only 
summarized in 
http://cr.openjdk.java.net/~alundblad/styleguide/feedback.html  I am 
including my draft comments below on V5 as many of them still apply to 
V6

Responses to the V5 feedback would also have been appreciated as I note, 
for example, that despite all the comments rejecting ASCII-only source 
files the V6 draft was not changed to UTF8.

Mike

---- V5 Feedback ----

OpenJDK Style Guide


General comments:
- Thank you for taking on this task. It is long overdue and important. 
It is also likely to be contentious and will probably leave everyone a 
little bit unsatisfied with some aspects. This is, though, how progress 
is made.
- I find that there is too much evidence of personal preference in the 
guide. Mostly in areas where there is not necessarily need to mention 
anything. If multiple equilavent choices are available and the only 
question is which one to pick for standardization it's important to be 
sure that anything need be said at all. Otherwise, yes, it is one to the 
benefits of taking on this task to be able to select your preference in 
matters where there are no technical or consistency reasons to suggest a 
particular option. As pass through the document with an eye to "do we 
really need to specify this" would remove most of these cases.

Specific comments:

Name: Perhaps call it "OpenJDK Style Guide" or if you must "OpenJDK Java 
Source Code Style Guidelines". This document does not claim to replace 
the old "Java Style Conventions". The title and scope is better stated 
by the first sentence of the introduction.

Motivation: Contrary to what I said in general comments, the statement 
about subjectivity is too strong. A stronger motivation for having these 
guidelines are to describe existing practice. Additionally the choices 
are not always subjective. Some are arbitrary though they are just as 
important to providing consistency.

Guiding principles: Needs a stronger statement of "don't make 
unnecessary changes to existing source only for better compliance with 
these guidelines." Having a reason to change source beyond guideline 
compliance is critical.

Java Source Files: 7-bit ASCII. Nope. UTF-8. There is considerable use 
of \u escapes including occasionally in silly places like the copyright 
character.  The character confusion issues are a non-compelling reason 
for disfavouring UTF-8. Selecting 7-bit ASCII in 2015 is quaint by 2025 
it will seem archaic.

Line endings: This is generally handled automatically by the version 
control client. Whatever Mercurial does for normalizing line endings in 
producing file/changes hashes should be what we are using (we don't 
actually have a choice do we?) and reference that rather than state it 
as a choice made by the project.

Special characters: The motivation should include that using only a 
single form will make searching easier. Also, \u000d and \u000a are not 
entirely usable in source files as they are translated before 
tokenization. The following doesn't work : String foo = "\u000d\u000a";

Wildcard imports: Under motivation. Wildcard imports were a convenience 
feature before autocompletion and IDE automatic management of imports 
were common. The necessity is much reduced with the modern IDE support.

Modifiers section could be moved earlier as it applies to 
class/enum/interface

Fields : It is worth making special mention of static fields. "Fields, 
especially static fields, should be declared final..."

Short forms: The final "Don'ts" for example seems perfectly normal to 
me. The getResult() case seems borderline. A motivation section is 
needed.

No tabs: Also implied by earlier no non-space whitespace rule.

switch dont's : I can think of a lot more examples of variance that 
might be prohibited including putting a statement on the same line as 
the label,

Wrapping lines: Rather than giving a limit on the total number of 
characters perhaps suggest that no more than 60-80 characters 
non-whitespace per line. The real problem with long lines is not the 
whitespace but the non-whitespace length.

Wrapping class declarations: too many permitted forms and the deep 
indenting puts the start near the line limit. The Collector example 
would be better splitting implements through { on to a single line. It 
would generally be preferable to keep the whole declaration for 
Collector on one line if it can be done sensibly.

Hexidecimal literals: lowercase literals probably outnumber uppercase 
literals at this point and the java library functions output lower case.

Javadoc: What's wrong in the second don't? The third don't will break 
due to '<String>' being interpreted as an html tag which is unclear. 
Perhaps suggest {@literal } for < and &

Names: Handling of acronyms deserves mention. URLHandler vs UrlHandler

Type variables : Use repeated letters for related type variables.  <T, 
TT extends T>

(my train ride was over at this point--additional feedback will be 
provided on future drafts)