[kepler-dev] Eclipse 3.1 Java Formatter

[Matt Jones]

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 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
> _______________________________________________
> 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
-------------------------------------------------------------------