[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