Description Steven Jin 2007-03-20 17:20:02 EDT

Java developers at Ford continuously use the automatic Format (Ctrl+Shift+F) feature to format their code.  However, they have noticed some unexpected behavior when using this feature on code snippets exist in the comments of a java file.  The customer uses the following HelloWorld class to demonstrate:
 
Example 1
public class HelloWorld {
    /**
     * <pre>
     * <property-group name="Communication">
     *     <property name="ConnectionFactoryJNDIName">QueueConnectionFactory</property>
     *     <property name="QueueJNDIName">AsyncSampleQueue</property>
     * </property-group>
     * </pre>
     * 
     * <pre>
     * Test
     * </pre>
     */
    public static void main(String[] args) {
        System.out.println("Hello World!");
    }
}
Many of their applications at Ford use property files to specify configuration parameters and they provide explanations of this information in their comments.  To ensure proper formatting, they enclose the property file sample content in <pre></pre> tags.  In the example above, the property group structure is some sample configuration information and the "Test" text is merely for demonstration purposes.  When you issue a Format command, the code looks like the following:
 
Example 2
public class HelloWorld {
    /**
     * <pre>
     *  &lt;property-group name=&quot;Communication&quot;&gt;
     *      &lt;property name=&quot;ConnectionFactoryJNDIName&quot;&gt;QueueConnectionFactory&lt;/property&gt;
     *      &lt;property name=&quot;QueueJNDIName&quot;&gt;AsyncSampleQueue&lt;/property&gt;
     *  &lt;/property-group&gt;
     * </pre>
     * 
     * <pre>
     * Test
     * </pre>
     */
    public static void main(String[] args) {
        System.out.println("Hello World!");
    }
}
 
As you can see in Example 2, the property group structure is correctly formatted automatically.  However, the property group content has been indented by an additional whitespace character due to the Format command.  However the "Test" text between the second set of <pre> tags has not been shifted to the right by one space.  After issuing ten Format commands, the code now appears as:
 
Example 3
public class HelloWorld {
    /**
     * <pre>
     *            &lt;property-group name=&quot;Communication&quot;&gt;
     *                &lt;property name=&quot;ConnectionFactoryJNDIName&quot;&gt;QueueConnectionFactory&lt;/property&gt;
     *                &lt;property name=&quot;QueueJNDIName&quot;&gt;AsyncSampleQueue&lt;/property&gt;
     *            &lt;/property-group&gt;
     * </pre>
     * 
     * <pre>
     * Test
     * </pre>
     */
    public static void main(String[] args) {
        System.out.println("Hello World!");
    }
}
 
As you continue to issue Format commands, this property group sample content will be shifted to the right indefinitely until it is manually corrected by the developer.  Given hundreds of files with thousands of lines of code at Ford, the manual correction of all the whitespace indenting quickly becomes intractable.  

The customer discovered that the following setting influenced the spacing.  In Rational Software Architect, select Window > Preferences > Java > Code Style > Formatter > Edit...  Looking at the General Settings groupbox of the Edit screen, you will see a "Format Java code snippets" setting.  De-selecting this box fixes the whitespace indenting problem; however, the character conversion functionality that occurred in the formatting from Example 1 to Example 2 no longer works.
 
The customer does not believe the code within the <pre> tags should be indenting over by one space each time Format is issued.  Assuming the "Format Java code snippets" setting is enable, the behavior the customer expects when issuing a Format command is 1.) the special characters should be properly converted, e.g. < becomes &lt; and 2.) no whitespace indenting should occur as is the case now.  The customer believes that within the "Format Java code snippets" program logic, there is code that is adding the additional whitespace each time the Format command is issued.  He believes that should be corrected.