[kepler-dev] Eclipse 3.1 Java Formatter
Christopher Brooks
cxh at eecs.berkeley.edu
Thu Jul 7 13:53:08 PDT 2005
Hi Matt,
I don't know of a command line interface to the Eclipse Formatter.
It would be nice if there was one. One of the advantages of Jalopy
is that it has a command line interface and plugins to Eclipse and
other IDEs.
It would be nice to run the formatter every night on the trees so
that the code was always fairly clean. We could also run
Source -> Organize Imports.
>From within Eclipse, to run the Eclipse Formatter on everything in a
package, go to the Package Explorer, right click on the package name,
select Source and then Format.
It would probably be good if we went with the same style. It seems
like the Java Convention Style is the way to go.
I'm going to wait until I hear from Edward before proceeding with
the Ptolemy II tree reformat operation though.
I'm concerned he is connecting via modem.
BTW - It looks like there is a certain amount of contention
about tabs vs. spaces in the Eclipse community, see
https://bugs.eclipse.org/bugs/show_bug.cgi?id=89739
and
http://dev.eclipse.org/newslists/news.eclipse.tools/msg19105.html
The Sun Coding Convention (last updated 1999) at
http://java.sun.com/docs/codeconv/html/CodeConventions.doc3.html#262
says:
"Four spaces should be used as the unit of indentation. The exact
construction of the indentation (spaces vs. tabs) is unspecified. Tabs
must be set exactly every 8 spaces (not 4)."
_Christopher
--------
Christopher --
Your proposal seems fine to me, and I think it would be good to run such
a thing over the kepler source too. Is there a command-line version of
the eclipse formatter or some other mechanism to reformat all the source
in a batch?
Matt
Christopher Brooks wrote:
> I took a look at the Eclipse 3.1 Java formatting and it looks fairly
> close to what we want.
>
> I started looking in to this now because of the upcoming Kepler Alpha
> release, where Kepler will be releasing code from the Ptolemy II
> CVS head. Dan will be tagging the Ptolemy II tree or otherwise
> copying the CVS head on Friday at the end of the day.
>
> I'm considering doing a wholesale reformat of the entire Ptolemy II
> tree, but this could cause problems for people who are connected via
> dialup.
>
> I don't want to engage in a big discussion about formatting pros and
> cons, my main question is:
>
> Should I reformat the Ptolemy II tree using the Eclipse Formatter with
> the Java Convention Style before the Kepler split.
>
>
> Below is my analysis:
>
> I updated $PTII/doc/coding/eclipse.htm to describe how to set up
> Eclipse 3.1.
>
> I started with the default Eclipse style. Note that there is also
> a Java Conventions Style, which I later found is similar to the
> Eclipse style.
> I discuss the Java Conventions Style at the end.
>
> I modified the tabs and added a closing newline.
> $PTII/doc/coding/eclipse.htm says:
>
>
>>Ptolemy II source files are worked on by many people with different
>>editors. Unfortunately, different text editors interpret tab
>>characters differently, so it is best to use spaces rather than tabs.
>>Also, it is best if files end with new line characters, so
>>that we can run line oriented scripts on them.
>>We handle the tabs and trailing new lines together:
>>
>> 1. Select Window -> Preferences in the menu.
>> 2. Expand the Java tree, select "Code Style" -> "Formatter" and then
>> Click on "Show"
>> 3. Under the "Indentation" tab, change the Tab policy to "Spaces only"
>> 4. Under the "New Lines" tab, select "at end of file"
>> 5. Click OK.
>> 6. You will be prompted to save the style with a new name, we
>> suggest "Ptolemy II", but you can select any name.
>
>
> BTW - it looks to me like the Eclipse default is just plain wrong.
> It looks like they are suggesting using tabs of four spaces.
> Tabs are almost always 8 spaces. Oh Well.
>
>
> To follow the discussion below, I suggest setting up Eclipse 3.1,
> opening up $PTII/ptolemy/kernel/util/NamedObj.java
> right clicking and selecting Source -> Format
>
> The compare the newly formatted file by right clicking
> and selecting Compare With -> Latest from Head.
>
> Below are my comments
>
>
> 1) We had been using Jalopy (http://jalopy.sourceforge.net/download.html)
> to add braces to if statements, which changes:
>
> if (foo == bar)
> return;
>
> To:
>
> if (foo == bar) {
> return;
> }
>
> The reason this is important is because if one does
>
> if (foo == bar)
> System.out.println("About to return");
> return;
>
> then the return is not part of the if statement. This is definitely
> one of my pet peeves, and I get caught by it periodically.
>
> Unfortunately, it looks like Eclipse 3.1 does not support this.
> However, there is a hack at
> http://kruithof.xs4all.nl/eclipseform/eclipsewithbraces.html
>
> I have not tried the above hack.
>
> I suppose I could get over this, but since I'm constantly looking at
> lots of code, it really drives me nuts.
>
> One issue is that Jalopy has not been updated in the past year. It
> looks like development has moved to the non-free version at
> http://www.triemax.com
>
> This is not a deal killer, since I can fix these problems
> separately.
>
>
> 2) In the head of the file, the Eclipse Formatter inserts
> a space, so the copyright is indented slightly.
>
> This is no problem.
>
>
> 3) The Eclipse Formatter inserts "// " before our nice ///// lines,
> so we get the following for the class comment:
>
> // //////////////////////////////////////////////////////////////////////
//
> // // NamedObj
>
> and:
> // /////////////////////////////////////////////////////////////////
> // // public methods ////
>
> The workaround would be to turn off comment formatting:
> Window -> Preferences -> Java -> Code Style -> Formatter
> Then click "Edit"
> In the Comments tab, uncheck "Enable comment Formatting"
>
> We could also try using different section separators?
>
>
> 4) The comment formatter also inserts * chars at the start
> of the class comment line.
>
> /**
> * This is a base class for almost all Ptolemy II objects.
> * <p>
>
> This change is ok with me. I forget why we don't have * chars now.
> I know that Zoltan prefers having leading * chars.
>
> However, to have this work, we need to have comment formatting
> enabled, which causes problem #3 above.
>
>
> 5) The comment formatter changes java doc comments from:
>
> /** Construct an object in the default workspace with the given name.
> * If the name argument is null, then the name is set to the empty
> * string. The object is added to the list of objects in the workspa
ce.
> * Increment the version number of the workspace.
> * @param name Name of this object.
> * @exception IllegalActionException If the name has a period.
> */
>
> To:
> /**
> * Construct an object in the default workspace with the given name.
If the
> * name argument is null, then the name is set to the empty string. T
he
> * object is added to the list of objects in the workspace. Increment
the
> * version number of the workspace.
> *
> * @param name
> * Name of this object.
> * @exception IllegalActionException
> * If the name has a period.
> */
>
> I'm not sure I like the change, but I could get used to this.
> Again, for this to work, we need to have comment formatting enabled,
> which caused problem #3 above.
>
> 6) The Formatter changes:
>
> throw new InternalErrorException(this, null,
> "This should not be happening: getAttribute()
"
> + "was called with a null name");
> To:
> throw new InternalErrorException(this, null,
> "This should not be happening: getAttribute()
"
> + "was called with a null name");
>
> I suppose this is technically more correct but I prefer how it was
> because we can get more text on the line.
>
> So, this is not a problem.
>
>
>
> 7) The Eclipse 3.1 Java Formatter makes some other changes.
> I tried indenting MoMLParser and in an inner class, these
> undocumented protected variables:
>
> protected String _portName;
> protected String _relationName;
> protected String _relation2Name;
> protected String _indexSpec;
> protected String _insideIndexSpec;
>
> became:
> protected String _portName;
>
> protected String _relationName;
>
> protected String _relation2Name;
>
> protected String _indexSpec;
>
> protected String _insideIndexSpec;
>
>
> 8) It looks like the Eclipse formatter changes
> if (foo)
> {
> bar;
> }
> with
> if (foo) {
> bar;
> }
>
> This is a great change!
> I'm really happy with it.
>
>
> I also tried the Java Conventions style.
> - By default, the Java Convention style does not use tabs (yay)
> - Under the "New Lines" tab, select "at end of file"
>
> The Java Convention Style looks even closer to our current style.
> The Java Convention Style has the // problem in #3 above
> Other than that, it looks fairly similar to the Eclipse style
>
> http://download.eclipse.org/eclipse/downloads/drops/S-3.1M6-200504011645/
eclipse-news-part3-M6.html
> says:
>
> --start--
> New Eclipse default built-in formatter profile
> Although Eclipse's default code formatter profile is named Java
> Convention, formatting a file using this profile uses tabs for
> indentation instead of spaces. A new profile named Eclipse has now
> been added which now reflects what the default formatter options
> have been all along, which uses tabs for indentation. To use true
> Java Convention settings, simply switch the formatter profile to
> Java Conventions using Java > Code Style > Formatter preference page.
> --end--
>
> So, I propose that I reformat the tree using the Java Convention
> default settings except for:
> Add a new line to the end of the file
> Disable comment formatting for the time being.
>
> With regard to comment formatting, we could post process the files
> and fix the results, but I'd rather stick with the default.
>
> Edward, if you have a fast connection, I could go ahead and unleash the
> formatter.
>
> _Christopher
> _______________________________________________
> Kepler-dev mailing list
> Kepler-dev at ecoinformatics.org
> http://mercury.nceas.ucsb.edu/ecoinformatics/mailman/listinfo/kepler-dev
--
-------------------------------------------------------------------
Matt Jones jones at nceas.ucsb.edu
http://www.nceas.ucsb.edu/ Fax: 425-920-2439 Ph: 907-789-0496
National Center for Ecological Analysis and Synthesis (NCEAS)
University of California Santa Barbara
Interested in ecological informatics? http://www.ecoinformatics.org
-------------------------------------------------------------------
--------
More information about the Kepler-dev
mailing list