[kepler-dev] Eclipse 3.1 Java Formatter
Shawn Bowers
sbowers at ucdavis.edu
Thu Jul 7 21:43:52 PDT 2005
Wearing my kepler developer hat, my only requirement is that all of this
means I don't have to make any changes to my XEmacs standard java
configuration (or at least only minimal changes) ;-)
Also, one question I have is if running the formatting over code in cvs
might result in extra hassle for developers in terms of ci/co. For
example, if I am working on a class, check it in, then make a few
changes that result in the code not compiling / functioning correctly
... then the next day fix up the code, will I end up with a conflict
when I check it in again?
BTW, thanks for taking the time to look into all of this.
shawn
Christopher Brooks wrote:
> 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
> -------------------------------------------------------------------
> --------
> _______________________________________________
> Kepler-dev mailing list
> Kepler-dev at ecoinformatics.org
> http://mercury.nceas.ucsb.edu/ecoinformatics/mailman/listinfo/kepler-dev
More information about the Kepler-dev
mailing list