Description Kirill Frolov 2001-11-24 02:13:53 EST

I propose the following advanced Java code formatter features for 
implementation:

1. When the indentation level is X (or i-th column), formatter shouldn't 
indent after that level (column)

2. When the formatter continues some complex expression on the new line, the 
continuation indent should be configurable

3. User should be able to configure the following items:
   * Should formatter preserve empty lines or not (this preference is already 
present) and is it should then how many lines to preserve (to be added)
   * Should formatter preserve line breaks or not
   * Should formatter preserve spaces or not

4. Should formatter place statements on the new line (always/never/as is)

5. Should formatter place simple body on the same line (always/never/as is)

6. Should formatter place 'else' on the same line (always/never/as is) - 
always and never preference already implemented

7. Should formatter keep array initialization (yes/no/yes but indent)

8. Should formatter align initialization (yes/no/class attributes only)
   Example:
     int i     = 5; // aligned 
     int iiiii = 5; // aligned 
     int a     = 34; // aligned 
     k = t * r; // not aligned because it is not an initialization

9. Should formatter surround simple body with braces (always/never/if on the 
next line)

10. position on the break operator in the switch block (normal/deindent)

11. Should formatter break an expression either before or after a binary 
operator 

12. Should formatter make empty lines around the declarations and is yes then 
how many in each of the following situations:
    * number of empty lines before class declaration
    * number of empty lines before class method
    * number of empty lines before class attribute
    * number of empty lines after class declaration
    * number of empty lines after class method
    * number of empty lines after class attribute

13. Should formatter insert spaces in expressions or not
    * space before control expression (between if/while/switch etc. and the 
following opening bracket)
    * space around binary operator (c=a+b or c = a + b)
    * spaces within parentheses
       ((x*y)+5)/3 or 
       ( ( x*y ) +5 ) /3 (provided that the previous option is off)
       ( ( x * y ) + 5 ) / 3 (provided that the previous option is on)
    * spaces within square brackets

Also I propose the followig Java and Javadoc comments formatter features for 
implementation:

1. Should formatter preserve spaces in comments or not

2. Format of C-style (/* xxx */) comments should include the following 
preferences:
   * Number of empty lines before a comment
   * Number of empty lines after a comment
   * Should formatter preserve line breaks in comments or not
   * Should formatter preserve empty lines in comments or not
   * Should formatter format small comments to occupy one line or not
     Example: imean should formatter transform
       /*
        abcde
       */
      to
       /* abcde */
   * Should formatter format c-style comments (I mean split into lines 
according to maximum line length preference)

3. Format inline comments (// xxx) should include the following preferences:
   * Whether to format inline comments (and use the following options) or not 
(simply skip them)
   * Inline comment separatior (one space/tab/none/as is)
   * Should formatter locate inline comment on a new line (always/never/as is)

4. Format Javadoc comments (/** xxx */) should include the following 
preferences:
   * Number of empty lines before a comment
   * Number of empty lines after a comment (the value of this preference is 
questionable because of the current javadoc implementation which consideres 
javadoc comment to describing the following item only if there is NO empty 
lines between javadoc and the item being described. But the future 
implementations may change this behaviour. Besides we can customize the 
default doclet within eclipse as a subproject (by the way it may also collect 
metrics))
   * Should formatter preserve line breaks within javadoc comments or not
   * Should formatter preserve empty lines within javadoc comments or not
   * Should formatter use one asterisk (*)/two asterisks(**)/or nothing to 
begin the consequent javadoc comment lines
     Example:
       /**
        * This is some comment
        */
     or
       /**
        ** This is some comment
        **/
     or
       /**
        This is some comment
        */
     Note: I prefer the second formatting option and all the following 
examples will use two asterisks
   * Should formatter fill the first line of javadoc with some char/empty 
line/disabled (char should be user-defined)
     Example:
       1. char fill (for example, '-')
         /** ------------------------------------------------
          ** This is some comment
          **/
       2. empty line
         /**
          ** This is some comment
          **/
       3. disabled
         /** This is sime comment
          **/
   * Should fprmatter fill the last line of javadoc with some char/empty 
line/disabled (char should be user-defined)
     Example is the same as for previous preference but it changes the last 
line of a comment:
       ------------------------------------------- **/
       **/
       This is some comment **/
   * Should formatter format short comments to occupy one line or not
     Example: should formatter transform 
       /** ******************************
        ** This is some comment
        ****************************** **/
     to
       /** This is some comment **/
   * Should formatter format javadoc comments (should it use the maximum line 
length preference to split comments into lines)


As a professional programmer I DO BELIEVE that these enhancements will make 
readability of code much better for EVERY programmer regardless of his own 
habit and style.
And besides there are a lot of other applications of formatter (only to 
mention: COMPARABLE code metrics, corporate code style and so on)