[kepler-dev] Eclipse 3.1 Java Formatter

[Christopher Brooks]

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 workspace.
     *  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. The
     * 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