[kepler-dev] Eclipse 3.1 Java Formatter

Christopher Brooks cxh at eecs.berkeley.edu
Fri Jul 8 12:26:24 PDT 2005


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