[kepler-dev] Eclipse 3.1 Java Formatter
Shawn Bowers
sbowers at ucdavis.edu
Fri Jul 8 22:15:05 PDT 2005
I'll have to try out the ptjavastyle.el, it sounds cool, along with the
jindent script.
Thanks,
shawn
Christopher Brooks wrote:
> Hi Shawn,
>
> Edward has fast net access until Tuesday, so I've committed the
> changes after running the Eclipse 3.1 Formatter.
>
> I use emacs quite a bit to edit code as well.
>
> We use ptII/util/lisp/ptjavastyle.el to implement the coding style.
> It seems fairly close.
>
> ptII/util/testsuite/jindent is a script that invokes emacs and
> reindents the code. Ptolemy II 5.0-beta was indented with this
> script.
>
> Since the devel tree will be indented with Eclipse, there will
> be some minor variation from the Emacs style. If you would like, we
> could work on ptjavastyle.el and see if we can get it closer.
> However, I think we could get by with doing nothing and reindenting
> the trees before the release.
>
> I agree that having the Formatter run automatically on the tree could
> be more trouble than it is worth. I'm not sure if we can run the
> Eclipse Formatter from a script.
>
> I think it is a best practice to do a cvs update and rebuild before
> editing files. I don't always do this because I think an edit will
> be small, and I sometimes end up regretting it.
>
> In the short term, I'm not setting up any thing that will
> automatically indent the code.
>
> _Christopher
>
> --------
>
>
> 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. Tab
> s
> > 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 s
> uch
> > 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 sou
> rce
> > in a batch?
> >
> > Matt
> >
> > Christopher Brooks wrote:
> > > I took a look at the Eclipse 3.1 Java formatting and it looks fairl
> y
> > > close to what we want.
> > >
> > > I started looking in to this now because of the upcoming Kepler Alp
> ha
> > > 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 vi
> a
> > > dialup.
> > >
> > > I don't want to engage in a big discussion about formatting pros an
> d
> > > cons, my main question is:
> > >
> > > Should I reformat the Ptolemy II tree using the Eclipse Formatter w
> ith
> > > 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 tab
> s.
> > >>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 th
> en
> > >> Click on "Show"
> > >> 3. Under the "Indentation" tab, change the Tab policy to "Spaces o
> nly"
> > >> 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 definitel
> y
> > > 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 a
> t
> > > 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 e
> mpty
> > > * string. The object is added to the list of objects in the w
> orkspa
> > 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 str
> ing. T
> > he
> > > * object is added to the list of objects in the workspace. Inc
> rement
> > 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: getAttri
> bute()
> > "
> > > + "was called with a null name");
> > > To:
> > > throw new InternalErrorException(this, null,
> > > "This should not be happening: getAttri
> bute()
> > "
> > > + "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-2005040
> 11645/
> > 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 option
> s
> > > have been all along, which uses tabs for indentation. To use tr
> ue
> > > Java Convention settings, simply switch the formatter profile t
> o
> > > 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/keple
> r-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