Eclipse code-style file

[GoogleCodeExporter]

For a more consistent look of the Java sources, I would suggest to use the 
attached Eclipse code formatter settings and use Eclipse's auto-format feature 
every once in a while. The attached style is largely the original Eclipse 
style, with a few minor exceptions, e.g. "extends", "implements" and "throws" 
are moved to the next line to make the code more readable.

The maximum line width is set to 100, the tab width is 4.

Original issue reported on code.google.com by richard.eckart on 19 Jun 2010 at 4:48

Attachments:

• java-style.xml

[GoogleCodeExporter]

I like having a shared style file.  I will look at this one.  Should be fine 
though.  

Original comment by pvogren@gmail.com on 20 Jun 2010 at 3:55

[GoogleCodeExporter]

One thing that is really bugging me about the current format style is the way 
angle braces are on the next line.  Such as:

class MyClass
{

}

Can we change this to be more like what the rest of the world does?  

For years I used angle brackets this way and only recently (about 4 years ago) 
changed to having the opening one appear on the same line.  So, I understand 
the appeal of having them the way we currently do.  However, after these few 
years of conforming to the java way, seeing them this way keeps distracting me 
and I would rather just have these brackets look like the rest of the java I 
work with.  Any objections? (I know I sound like I'm whining here....)

Original comment by pvogren@gmail.com on 27 Dec 2010 at 7:53

[GoogleCodeExporter]

[deleted comment]

[GoogleCodeExporter]

We should stick to the standard Java code conventions as much as possible:

http://www.oracle.com/technetwork/java/codeconventions-150003.pdf

6.4 Class and Interface Declarations
• Open brace “{” appears at the end of the same line as the declaration 
statement

7.2 Compound Statements
• The opening brace should be at the end of the line that begins the compound 
statement

So a big +1 from me on putting the opening braces where Java does.

Original comment by steven.b...@gmail.com on 28 Dec 2010 at 2:44

[GoogleCodeExporter]

I am not in favor of having the brackets on the same line. As long as I can   

think i have put them on the following line. I think it is because I like   

having the signature/header well separated from the body. The class header 
  
or method signature can become rather complex with   

extends/implements/throws and generic types and having to search for where 
  
that ends and where the body begins is what I think I do not like. For 
the   
same reason I am not in favor of having the complex header stuff all 
in one   
line or line-broken "simply" - instead I like having separate 
parts of the   
header/signature on different lines, such as at least 
visibility modifiers,   
names and arguments on one and 
extends/implements/throws on another. Indeed   
I even like having it more 
refined, but I find little support for a more   
refined way in tools and 
people. 

(apologies for getting this twice)

Original comment by richard.eckart on 28 Dec 2010 at 2:55

[GoogleCodeExporter]

I like having readable code much more than sticking to conventions. I even tend 
to break conventions if necessary in order to have better readable code. If the 
convention does not help getting readable code, it only fulfills 50% of its 
mission imho - the other 50% being to have uniform code.

Original comment by richard.eckart on 28 Dec 2010 at 2:55

[GoogleCodeExporter]

Richard,  I really do sympathize with what you are saying here.  I think the 
Java community should have gone the other way with the brackets and I used the 
"next line" style for a very long time.  But they didn't and I agree with Steve 
that we should stick with the convention.  For me, it is the conventions that 
make Java readable.  It is probably more important for Java than for other 
languages because it is so verbose.  Java suffers in readability because there 
is so much of it - but having formatting conventions can really help with this. 
 The reason I switched my bracketing style is because I could always tell the 
difference between my code and other people's code.  I find this very 
distracting and it adversely effects readability for me.  

I also prefer the "end-of-line" style now because I am used to it.  So, I will 
add that I serve as a single data point that suggests that a person (you) that 
is entrenched in "same-line" bracketing can get used to the "end-of-line" style 
and even prefer it.  

One thing that can alleviate the concern you raised above is to extend the line 
wrap to 120 characters.  Everywhere I've worked in the last 5 years has used 
120 characters and I think this improves readability a lot.  

That is also to say - I don't think we need to strictly adhere to a set of 
guidelines from 1997.  I think it would make sense to see if the UIMA project 
has a set of formatting style files.  That would be my vote.  

Original comment by pvogren@gmail.com on 28 Dec 2010 at 3:59

[GoogleCodeExporter]

UIMA has the same convention as Java for the braces:
http://uima.apache.org/codeConventions.html
I agree with Philip that the brace-on-following-line style is harder for me to 
read, mainly because it differs from almost all other Java code.

They also wrap at 100 characters, so we should probably stick with that. I find 
120 hard to read - I typically don't work with the editor expanded up to 120 
characters. I'd love to go down to 80, but that's just not practical with a 
verbose language like Java.

Original comment by steven.b...@gmail.com on 28 Dec 2010 at 4:36

[GoogleCodeExporter]

http://uima.apache.org/codeConventions.html

Original comment by pvogren@gmail.com on 28 Dec 2010 at 4:43

[GoogleCodeExporter]

Steve, I didn't see your comment before I added the url.  I also vote for using 
the UIMA formatting.  It was really easy for me to update the formatting with 
the xml file they give on the above link.  

Original comment by pvogren@gmail.com on 28 Dec 2010 at 5:03

[GoogleCodeExporter]

I am against the UIMA code style even more because they use a 2 space indent 
instead of a 4 space indent. In my experience a code that nests so deep that it 
doesn't fit in 100 chars with a 4 space indent should be split up into methods 
to provide for a better readability.

Other than that they are as bad as the Java code style they inherit from.

I tried having a look at what coding styles are out there 
(http://en.wikipedia.org/wiki/Indent_style) - but looking briefly I actually 
found no rationale being given for a particular style. From reading that 
article I get the impression that in order to set a style one needs to write a 
book on programming. 

Well, I haven't written a book on programming. If you insist we'll have it your 
way - whatever that is - because you are two and I am one and this is a 
democratic project. I'll not change my vote though:

- EOL brackets: no
- Tab width/indentation: 4
- Line width: 100

Btw. I configure the EOL-type in the Eclipse workspace settings to "Windows" 
even though I am working on OS X or Linux. The reason for this is, that I make 
a concession to the poor Windows users often suffer from editors that are not 
aware that Windows is not the only system on Earth and would render everything 
into a single line.

I suggest configuring EOL-type as well as encoding (UTF-8) in the Eclipse 
workspace. In particular encoding could not be configured anywhere else anyway.

Original comment by richard.eckart on 28 Dec 2010 at 5:37

[GoogleCodeExporter]

I agree with you about the 2-space indent.  That's pretty silly.  

My vote, for the record, is:

- EOL brackets: yes
- Tab width/indentation: 4
- Line width: 120

Now that I see that the UIMA convention agrees with me on 1 of 3 of these, I 
like it a lot less!  I realize it's all arbitrary and that I appeal to 
convention when it suits me.  sigh.

I will concede on any of these except the four space indent.  I don't think I 
care about the EOL bracketing as much as Richard does - so I will back off that 
vote unless Steve makes a fuss.  Steve?

Original comment by pvogren@gmail.com on 28 Dec 2010 at 5:56

[GoogleCodeExporter]

Ok put me down for:

- EOL brackets: yes
- Tab width/indentation: 4
- Line width: 100

At least we all agree that 2 space indentation is just silly. ;-)

Original comment by steven.b...@gmail.com on 28 Dec 2010 at 6:33

[GoogleCodeExporter]

I was just reconfiguring my project-specific code style for uimaFIT in Eclipse 
and there springs me in the eye why I do not like EOL brackets. In the 
following example I do have problems seeing where the body starts because the 
first indented line is a wrapped throws and not the actual method body.

(In the following example the line length is 40 to force early line wraps for 
demonstration purposes - this is the default in the Eclipse Preferences 
Formatter editor)

/**
 * 'throws' clause
 */
class Example
{
    int foo() throws FirstException,
        SecondException, ThirdException {
        return Other.doSomething();
    }
}

That is an example why I prefer this style:

/**
 * 'throws' clause
 */
class Example
{
    int foo()
        throws FirstException,
        SecondException, ThirdException
    {
        return Other.doSomething();
    }
}

Original comment by richard.eckart on 29 Dec 2010 at 12:50

[GoogleCodeExporter]

Agreed that the above wrapping is really bad, but I find both examples equally 
hard to read because they indent the wrapped definition at the same level as 
the method body.

Can we set our wrapping so that this kind of thing doesn't happen? The Java 
code conventions seem to suggest that "SecondException" should be aligned with 
"FirstException", or indented an extra level (3 tabs instead of 2) to avoid 
looking like it's part of the block:

http://www.oracle.com/technetwork/java/codeconventions-136091.html#248

I would also be fine with aligning "throws" with "int".

Original comment by steven.b...@gmail.com on 29 Dec 2010 at 1:14

[GoogleCodeExporter]

I would love to align "throws" with "int" - that is my preferred style. 
Unfortunately I am unable to get Eclipse to support this in its formatter. At 
one time I actually patched the formatter code to support that... when can I 
write code they way I want to I use this:

/**
 * 'throws' clause
 */
class Example
{
    int foo()
    throws FirstException,
        SecondException, ThirdException
    {
        return Other.doSomething();
    }
}

I understand what Oracle suggests is possible to configure in Eclipse, but I 
find it confusing that the header "closes" on a different indentation level 
that it "opens". I think it is a style-hack to indent the throws twice to make 
it distinguishable from the body. In my opinion this hack works around the 
EOL-bracket. It is completely beyond me why they prefer this hack instead of 
simply putting the bracket to the next line.

/**
 * 'throws' clause
 */
class Example
{
    int foo()
            throws FirstException,
            SecondException, ThirdException {
        return Other.doSomething();
    }
}

Original comment by richard.eckart on 29 Dec 2010 at 2:06

[GoogleCodeExporter]

> It is completely beyond me why they prefer this hack instead of simply 
putting the bracket to the next line.

I think I already answered this above - it's because the extra brace doesn't 
help when the blocks still align. When you're scanning through code, it's much 
easier to see the block structure than to look for the tiny brace characters.

> I would love to align "throws" with "int"

I think you can get something like this by setting "Default indentation for 
wrapped lines" to 0, setting "Wrap first element, others where 
necessary"/"Default indentation" for "throws clause" (and maybe a few other 
things like "extends clause" and "implements clause") and then setting "Wrap 
where necessary"/"Indent on column" for everything else.

Original comment by steven.b...@gmail.com on 29 Dec 2010 at 3:01

[GoogleCodeExporter]

> I think I already answered this above - it's because the extra brace doesn't 
help when the blocks still align. When you're scanning through code, it's much 
easier to see the block structure than to look for the tiny brace characters.

I think the mostly empty line on which the brace is located helps me locating 
the boundary between header and body - not the brace character.  Recently I 
have seen some code from a colleague and wondered why he started every method 
with an empty line. I think this was also a hack to get the separation effect 
of putting the brace on the next line without actually doing it. This way the 
code complies with the standard Eclipse settings (aka. Oracle/Sun guidelines) 
but gets the separation. A subversive approach indeed ;)

    int foo() throws FirstException,
        SecondException, ThirdException {

        return Other.doSomething();
    }

> I think you can get something like this by setting "Default indentation for 
wrapped lines" to 0, setting "Wrap first element, others where 
necessary"/"Default indentation" for "throws clause" (and maybe a few other 
things like "extends clause" and "implements clause") and then setting "Wrap 
where necessary"/"Indent on column" for everything else.

The problem is that setting the default indentation to 0, I can no longer tell 
Eclipse to indent the wrapped exceptions

    int foo()
    throws FirstException,
    SecondException, ThirdException {
        return Other.doSomething();
    }

whereas I want

    int foo()
    throws FirstException,
        SecondException, ThirdException {
        return Other.doSomething();
    }

I think the problem is that Eclipse does not make a separation between the 
"arguments" to the throw keyword and the keyword itself. So I cannot tell it to 
break the line before the keyword but then properly indent the exception list.

Anyway, the problem remains then, that the wrapped exceptions seem like the 
first line of the body because the header is not well separated from the body  
- by an empty line or a line containing only a brace.

Original comment by richard.eckart on 29 Dec 2010 at 5:09

[GoogleCodeExporter]

So maybe we can compromise on "Same line" braces, but "Blank Lines/At beginning 
of method body = 1"?

Here's a specific proposal. Start with the standard Java formatter (all braces 
set to "Same line") and then tweak:

* Tab policy - spaces only
* Blank lines - Before first declaration - 1
* Blank lines - At beginning of method body - 1
* Line wrapping - Maximum line width - 100

That will give us:

    int foo() throws FirstException,
            SecondException,
            ThirdException {

        return Other.doSomething();
    }

That way, you get your extra-line-marks-beginning-of-block, and I get my 
don't-wrap-definitions-at-the-same-level-as-the-block.

Original comment by steven.b...@gmail.com on 29 Dec 2010 at 8:36

[GoogleCodeExporter]

If we augment the proposal by moving the brace to the now empty line, sure ;) 
If you suggest having a blank line, what is it that you gain by keeping the 
brace at the EOL?

Original comment by richard.eckart on 29 Dec 2010 at 8:41

[GoogleCodeExporter]

I find the extra brace distracting (just as Philip said in his first post about 
this).

But if we can't find a compromise proposal, then we should probably revert to 
an existing standard set of conventions that we can all hate equally. ;-)

Original comment by steven.b...@gmail.com on 29 Dec 2010 at 8:54

[GoogleCodeExporter]

If i could as I like, I would write the code like this:

public
class SuperFoo<E extends Edge, N extends Node>
extends Foo<E, N>
implements Super
{
    public static <E extends Edge, N extends Node>
    SuperFoo create(
        final Class<E> edgeClass, 
        final Class<N> nodeClass)
    throws IOException
    {
        return new SuperFoo<E, N>(edgeClass, nodeClass);
    }
}

Actually it was when I first wrote a generics-based set of classes for graphs 
that I came up with this style. Features are:

- throws, implements, extends on a separate line without indent
- modifiers on a separate line without indent
- brackets next line for good separation of header from body
- supports "collapse" feature in Eclipse well (e.g. method collapses to 
"SuperFoo create("
- each argument on a separate line to support complex/generic arguments
- in total the style scales quite well to complex classes and methods but uses 
significant space for some simple methods

With any of the "default" styles that put everything into a single line, stuff 
just becomes completely unreadable. Unfortunately Eclipse does (as discussed 
previously) not support this. Also I have trouble convincing people that 
keeping method modifiers and generics on a separate line is useful, since most 
of the time methods and classes are much simpler. So I usually compromise to 
the following form - here only "extends", "implements" and "throws" are on a 
separate line. This keeps some of the readability. The method signature becomes 
less readable, but also uses less space - in particular for simple methods. 

public class SuperFoo<E extends Edge, N extends Node>
    extends Foo<E, N>
    implements Super
{
    public static <E extends Edge, N extends Node> SuperFoo create(final Class<E> edgeClass, final Class<N> nodeClass)
        throws IOException
    {
        return new SuperFoo<E, N>(edgeClass, nodeClass);
    }
}

I suppose I am whining too, but I have a hard time making more concessions - in 
particular with respect to the placement of the braces. If you think it 
necessary to sacrifice convention over readability then... well... let's go 
with Steve's options:

- EOL brackets: yes
- Tab width/indentation: 4
- Line width: 100

... but then we should make it a requirement that each committer turns on 
Eclipse's "format on save" feature to enforce the style. I know that at least I 
can't get my fingers to write such code.

Original comment by richard.eckart on 29 Dec 2010 at 9:34

[GoogleCodeExporter]

all the code is formatted.  I made a note about formatting conventions on the 
DeveloperSetup page.

Original comment by pvogren@gmail.com on 3 Jan 2011 at 11:28

• Changed state: Fixed

[GoogleCodeExporter]

Original comment by richard.eckart on 7 Apr 2011 at 12:12

• Added labels: Milestone-1.2.0

[GoogleCodeExporter]

Original comment by richard.eckart on 8 May 2011 at 10:43

[GoogleCodeExporter]

hello how can i get eclipse to do this automatically

public class hello
{

    public static void main(String[] args)
    {
        // TODO Auto-generated method stub

    }//end Main        <--
}//end class               <--

arrows point at what needs to be formatted automatically right now its 
displaying

}
//end class

Original comment by dillpick...@gmail.com on 5 Mar 2012 at 9:43

[GoogleCodeExporter]

I have no idea. Eclipse should have that nice feature from IntelliJ which shows 
the block opening lines in a nice little tooltip at the top/bottom of the 
screen if they do not fit into the editor window. I personally don't like these 
comments ;)

Original comment by richard.eckart on 6 Mar 2012 at 8:16

[GoogleCodeExporter]

its mainly for my class that is the way my teacher does it

Original comment by dillpick...@gmail.com on 6 Mar 2012 at 5:03