Jindent - Java Source Code Formatter http://www.jindent.com
 

previous topic  Previous:  Policy Next:  Method Calls   next topic

title
5.6.2.9.3 Declarations

Variables/Fields

Maximal gap size of indentations for multiple variable and field declarations

Maximal gap size of indentations for multiple variable and field declarations

Detects big gaps in field and local variable declarations caused by line wrapping and reindents these declarations again with a smaller indentation size.

Please note: This setting is similiar to "Maximal gap size of indentations" but in this case its use is just related to formatting of local variable and field declarations.



An example describes the definition of 'big gap'. We assume a line wrapping result like this:

class MyConstants                                                             |
{                                                                             |
    public:                                                                   |
        static char[] constantOne   = "Some text here ...",                   |
|--------------------|constantTwo   = "Some other text...",                   |
                      constantThree = CALC_TEXT_MESSAGE(                      |
                                          "parameter"),                       |
                      constantFour  = "bla bla ...";                          |
}                                                                             |

The example above shows a correct line wrapping. 'constantTwo' is aligned to 'constantOne' and so on. Even if this is a correct alignment the big gap appearing between left margin and 'constantTwo' does not look pretty.

To handle this problem we introduce two gap size measures:


Now one of these two measurements can be used to detect 'big gaps' in source codes. If a big gap is found then Jindent uses the value from setting: "General indentation size" to reindent this source code again.


An example explains the algorithm:

We assume setting "General indentation size" is set to 4.
Setting "Maximal gap size of indentations for multiple variable and field declarations" is using a 'relative' detection mode for big gaps and the maximal allowed size of these gaps is 12.

Now Jindent would procced the following steps:


Use setting infinite to leave gaps untouched.

Use setting 0 and Jindent will always use "General indentation size" to indent all variable and field declarations.

See also... See also: Maximal gap size of indentations , Align assignments




Wrap initializers of variable and field declarations to right side (in this case the 'maximal gap settings' will be ignored)

Wrap initializers of variable and field declarations to right side (in this case the 'maximal gap settings' will be ignored)

Controls whether line wrapping of variable or field initializers are proceed to the right side of assignment or not.


Do not wrap initializers to right side:

LongClassName tmp;                                          |
char[]        stringValue1 = "some text here ...";          |
char[]        stringValue2 = CALC_TEXT_MESSAGE(             |
    parameter1, parameter2);                                |



Wrap initializers to right side:

LongClassName tmp;                                          |
char[]        stringValue1 = "some text here ...";          |
char[]        stringValue2 = CALC_TEXT_MESSAGE(             |
                                 parameter1, parameter2);   |


Please note:In this case the setting overwrites the functionality of: "Maximal gap size of indentations"


Constructors/Methods

Wrap after method declaration return types

Wrap after method declaration return types

Controls how to wrap after return types of method declarations.


Wrap always:

float                                   
method()                                
{                                       
    ...                                 
}                                       

This wrapping mode wraps always after return types of method declarations even if the line would fit into the specified maximal line length.


Wrap never:

float method()                          
{                                       
    ...                                 
}                                       

This wrapping mode never wraps after return types of method declarations even if the line does not fit into the specified maximal line length.


Wrap on demand:

static float                                      |
aPrettyLongMethodNameWhichCannotBeWrapped()       |
{                                                 |
    ...                                           |
}                                                 |

This wrapping mode wraps on demand:
If the method return type fits into specified maximal line length then it won't be wrapped. If it exceeds maximal line length the return type will be wrapped after its return type though.


Wrapping mode if line exceeds works a bit different:
If the method declaration line exceeds maximal line length then the line will be wrapped after its return type.


We assume the following input source code example which exceeds maximal line length:

static int longMethodName(int paramaterOne, int parameterTwo)
{                                                      |
    ...                                                |
}                                                      |

In this example token parameterTwo exceeds the specified maximal line length, therefore we consider this case as 'the line exceeds maximal line length' and it will be wrapped after its return type:

static int                                             |
longMethodName(int paramaterOne, int parameterTwo)     |
{                                                      |
    ...                                                |
}                                                      |




Wrap before left parentheses (

Wrap before left parentheses (

Controls how to wrap before left parentheses of method/constructor declarations.

Please note:This setting does not affect method/constructor declarations without any parameters.


Wrap always:

void method                             
    (int parameterOne, int parameterTwo)
{                                       
    ...                                 
}                                       

This wrapping mode wraps always before left parentheses of method/constructor declarations even if the line would fit into the specified maximal line length.
The wrapped line is indented by setting: "Indentation of wrapped left parentheses ("
Wrapped parameters will be be aligned to its corresponding first parameter.


Wrap never:

void method(int parameterOne, int parameterTwo)
{                                       
    ...                                 
}                                       

This wrapping mode never wraps before left parentheses of method/constructor declarations even if the line does not fit into the specified maximal line length.


Wrap on demand:

static void aPrettyLongMethodName       |
    (int parameterOne)                  |
{                                       |
    ...                                 |
}                                       |

This wrapping mode wraps on demand:
If the left parenthesis of method/constructor declaration fits into specified maximal line length then it won't be wrapped. If it exceeds maximal line length the left parenthesis will be wrapped though.


Wrapping mode if line exceeds works a bit different:
If the method/constructor declaration line exceeds maximal line length then the line will be wrapped before its left parenthesis.


We assume the following input source code example which exceeds maximal line length:

static int longMethodName(int paramaterOne, int parameterTwo)
{                                                      |
    ...                                                |
}                                                      |

In this example token parameterTwo exceeds the specified maximal line length, therefore we consider this case as 'the line exceeds maximal line length' and it will be wrapped after its left parenthesis:

static int longMethodName                              |
    (int paramaterOne, int parameterTwo)               |
{                                                      |
    ...                                                |
}                                                      |

Indentation of wrapped line is done by setting: "Indentation of wrapped left parentheses ("

See also... See also: Indentation of wrapped left parentheses (




Indentation of wrapped left parentheses (

Indentation of wrapped left parentheses (

Indents wrapped left parentheses of method/constructor declarations by a specified number of white spaces.

See also... See also: Wrap before left parentheses (




Wrap first parameter

Wrap first parameter

Controls how to wrap first parameters of method/constructor declarations.


Wrap always:

void method(                            
    int parameterOne, int parameterTwo) 
{                                       
    ...                                 
}                                       

This wrapping mode wraps always the first parameter of method/constructor declarations even if the line would fit into the specified maximal line length.
The wrapped line is indented by setting: "Indentation of first wrapped parameter"


Wrap never:

void method(int parameterOne, int parameterTwo)
{                                       
    ...                                 
}                                       

This wrapping mode never wraps first parameter of method/constructor declarations even if the line does not fit into the specified maximal line length.


Wrap on demand:

static void aPrettyLongMethodName(                |
    int parameterOne, int parameterTwo)           |
{                                                 |
    ...                                           |
}                                                 |

This wrapping mode wraps on demand:
If the method/constructor parameters fit into specified maximal line length then it won't be wrapped. If it exceeds maximal line length the first parameter will be wrapped though.


Wrapping mode if line exceeds works a bit different:
If the method/constructor declaration line exceeds maximal line length then the first parameter will be wrapped.


We assume the following input source code example which exceeds maximal line length:

static int longMethodName(int paramaterOne, int parameterTwo)
{                                                      |
    ...                                                |
}                                                      |

In this example token parameterTwo exceeds the specified maximal line length, therefore we consider this case as 'the line exceeds maximal line length' and first parameter will be wrapped:

static int longMethodName(                             |
    int paramaterOne, int parameterTwo)                |
{                                                      |
    ...                                                |
}                                                      |

Indentation of wrapped line is done by setting: "Indentation of first wrapped parameter"


Indentation of first wrapped parameter

Indentation of first wrapped parameter

Indents first wrapped parameter of method/constructor declarations by a specified number of white spaces.

See also... See also: Wrap first parameter




Wrap all other parameters

Wrap all other parameters

Controls how to wrap parameters of method/constructor declarations.


Wrap always:

void method(int parameterOne,           
                   int parameterTwo,    
                   int parameterThree)  
{                                       
    ...                                 
}                                       

This wrapping mode wraps always parameters of method/constructor declarations even if the line would fit into the specified maximal line length.


Wrap never:

void method(int parameterOne, int parameterTwo, int parameterThree)
{                                       
    ...                                 
}                                       

This wrapping mode never wraps parameters of method/constructor declarations even if the line does not fit into the specified maximal line length.


Wrap on demand:

void method(int parameterOne, int parameterTwo,             |
                   int parameterThree)                      |
{                                                           |
    ...                                                     |
}                                                           |

This wrapping mode wraps on demand:
If the parameters of method/constructor declarations fit into specified maximal line length then they won't be wrapped. If they exceed maximal line length they will be wrapped though.


Wrapping mode if line exceeds works a bit different:
If the method/constructor declaration line exceeds maximal line length then all parameters will be wrapped.


We assume the following input source code example which exceeds maximal line length:

void method(int parameterOne, int parameterTwo, int parameterThree)
{                                                                |
    ...                                                          |
}                                                                |

In this example token parameterThree exceeds the specified maximal line length, therefore we consider this case as 'the line exceeds maximal line length' and all parameters will be wrapped:

void method(int parameterOne,                                    |
                   int parameterTwo,                             |
                   int parameterThree)                           |
{                                                                |
    ...                                                          |
}                                                                |



Wrap before right parentheses )

Wrap before right parentheses )

Controls how to wrap right parentheses of method/constructor declarations.

Please note:This setting does not affect method/constructor declarations without any parameters.


Wrap always:

void method(int parameterOne, int parameterTwo
)                                       
{                                       
    ...                                 
}                                       

This wrapping mode wraps always right parentheses of method/constructor declarations even if the line would fit into the specified maximal line length.


Wrap never:

void method(int parameterOne, int parameterTwo)
{                                       
    ...                                 
}                                       

This wrapping mode never wraps right parentheses of method/constructor declarations even if the line does not fit into the specified maximal line length.


Wrap on demand:

static void aPrettyLongMethodName(int parameterOne, int parameterTwo
)                                                                   |
{                                                                   |
    ...                                                             |
}                                                                   |

This wrapping mode wraps on demand:
If the right parenthesis of method/constructor declarations fits into specified maximal line length then it won't be wrapped. If it exceeds maximal line length the right parenthesis will be wrapped to a new line though.


Wrapping mode if line exceeds works a bit different:
If the method/constructor declaration line exceeds maximal line length then the line will be wrapped before its right parenthesis.


We assume the following input source code example which exceeds maximal line length:

static int longMethodName(int paramaterOne, int parameterTwo)
{                                                      |
    ...                                                |
}                                                      |

In this example token parameterTwo exceeds the specified maximal line length, therefore we consider this case as 'the line exceeds maximal line length' and right parenthesis will be wrapped:

static int longMethodName                              |
(                                                      |
    int paramaterOne,                                  |
    int parameterTwo                                   |
)                                                      |
{                                                      |
    ...                                                |
}                                                      |
In this example we additionally set "Wrap first parameter" and "Wrap before right parentheses )" to if line exceeds too.



Indentation of wrapped right parentheses )

Indentation of wrapped right parentheses )

Indents wrapped right parentheses of method/constructor declarations by a specified number of white spaces.

See also... See also: Wrap before right parentheses )




Avoid confusing indentations for methods and constructors declarations

Avoid confusing indentations for methods and constructors declarations

Detects 'confusing indentations' in method/constructor declarations caused by line wrapping and reindents these source code lines again with a new alternative indentation size.


Explanation of definition 'confusing indetation':

The following source code example is wrapped properly. int parameterTwo is correctly aligned to parameterOne:

void                                              |
set(int parameterOne,                             |
    int parameterTwo) {                           |
    callAnotherMethod(paramterOne, paramaterTwo);        // line is easy to miss
}                                                 |

Even if this wrapping is correct at first glance the method call callAnotherMethod(...) is easy to miss. It seems it belongs to the method declaration head. Such an indetation is considered as 'confusing indentation'.
To handle this problem Jindent is able to detect this 'confusing indentations' and rather use the indentation size of "Alternative indentation for 'maximal gap' and 'confusing indentations' settings" to reindent the originate source code elements.


The example above now looks like:

void                                              |
set(int parameterOne,                             |
|------|int parameterTwo) {                       |
    callAnotherMethod(paramterOne, paramaterTwo);        // line is easy to miss
}                                                 |

For setting "Alternative indentation for 'maximal gap' and 'confusing indentations' settings" we assume a value of 8.
The line callAnotherMethod(...) is now separated from the method head and well-defined.

Please note: There are only rare code conventions where 'confusing indentation' can appear in method/constructor declarations.
If you don't know how to use this setting we recommend to disable it.


See also... See also: Alternative indentation for 'maximal gap' and 'confusing indentations' settings , Avoid confusing indentations




Wrap before throw

Wrap before throw

Controls how to wrap token throw.


Wrap always and indent by 8 white spaces:

static void method(int args)            
        throw (MyError) {               
    callMethod();                       
}                                       

This wrapping mode wraps always token throw to a new line even if it would fit into the specified maximal line length.
The wrapped token throw is indented by setting: "Indentation of wrapped throw"


Wrap never :

static void method(int args) throw (MyError) {
    callMethod();                       
}                                       

This wrapping mode never wraps token throw to a new line even if it does not fit into the specified maximal line length.


Wrap on demand and indent by 8 white spaces:

static void method(int args)            |
        throw (MyError) {               |
    callMethod();                       |
}                                       |

This wrapping mode wraps token throw on demand:
If token throw fits into the specified maximal line length then it won't be wrapped. If it exceeds maximal line length it will be wrapped to a new line though. The wrapped token will be indented by setting: "Indentation of wrapped throw"


Wrapping mode if line exceeds works a bit different:
If the line where token throws belongs to exceeds maximal line length then throws will be wrapped.


We assume the following input source code example which exceeds maximal line length:

static void method(int args) throw(overflow, underflow) {
    callMethod();                                      |
}                                                      |

In this example token throws does not exceed the specified maximal line length, but another token underflow does. We consider this case as 'the line exceeds maximal line length' and therefore token throws will be wrapped and indented by setting: "Indentation of wrapped throw"

static void method(int args)                           |
        throw (overflow, underflow) {                  |
    callMethod();                                      |
}                                                      |


See also... See also: Indentation of wrapped throw




Indentation of wrapped throw

Indentation of wrapped throw

Indents wrapped token throw by a specified number of white spaces.

See also... See also: Wrap before throw




Wrap throw exceptions

Wrap throw exceptions

Controls how to wrap exceptions of method/constructor declarations.


Wrap always:

void method(int parameterOne) throw(overflow,
                                    underflow,
                                    zero_devide) {
    ...                                 
}                                       

This wrapping mode wraps always exceptions of method/constructor declarations even if the line would fit into the specified maximal line length.


Wrap never:

void method(int parameterOne) throw(overflow, underflow, zero_devide) {
    ...                                 
}                                       

This wrapping mode never wraps exceptions of method/constructor declarations even if the line does not fit into the specified maximal line length.


Wrap on demand:

void method(int parameterOne) throw(overflow, underflow,         |
                                    zero_devide) {               |
    ...                                                          |
}                                                                |

This wrapping mode wraps on demand:
If the exceptions of method/constructor declarations fit into specified maximal line length then they won't be wrapped. If they exceed maximal line length they will be wrapped though.


Wrapping mode if line exceeds works a bit different:
If the method/constructor declaration line exceeds maximal line length then all exceptions will be wrapped.


We assume the following input source code example which exceeds maximal line length:

void method(int parameterOne) throw(overflow, underflow, zero_devide) {
    ...                                                               |
}                                                                     |

In this example token zero_devide exceeds the specified maximal line length, therefore we consider this case as 'the line exceeds maximal line length' and all exceptions will be wrapped:

void method(int parameterOne) throw(overflow,                         |
                                    underflow,                        |
                                    zero_devide) {                    |
    ...                                                               |
}                                                                     |



Do not wrap empty void parameter

Do not wrap empty void parameter

Depending on your code convention it can be necessary to put method parameter on separated lines, for instance:




int method                                   |
(                                            |
    int parameterOne,                        |
    int parameterTwo,                        |
    int parameterThree                       |
)                                            |
{                                            |
    ...                                      |
}                                            |
The same formatting style will of course be applied to void parameter declarations like:




int method                                   |
(                                            |
    void                                     |
)                                            |
{                                            |
    ...                                      |
}                                            |
You can overwrite this behaviour by enabling 'Do not wrap void parameter'. The output will now look like:




int method(void)                             |
{                                            |
    ...                                      |
}                                            |
The void parameter will not be wrapped to a new line.


Enums

Wrap Enum constants

Wrap Enum constants

Controls how to wrap constants in enumeration declarations.


Wrap enum constants on demand:

enum Counter {                               |
    ONE, TWO, THREE, FOUR, FIVE, SIX, SEVEN, |
    EIGHT, NINE, TEN                         |
};                                           |


Wrap enum constants always:

enum Seasons {                               |
    SPRING,                                  |
    SUMMER,                                  |
    AUTUMN,                                  |
    WINTER                                   |
};                                           |


Wrap enum constants if line exceeds:

enum Seasons {                               |
    SPRING, SUMMER, AUTUMN, WINTER           |
};                                           |
                                             |
enum Counter {                               |
    ONE,                                     |
    TWO,                                     |
    THREE,                                   |
    FOUR,                                    |
    FIVE,                                    |
    SIX,                                     |
    SEVEN,                                   |
    EIGHT,                                   |
    NINE,                                    |
    TEN                                      |
};                                           |



Maximal number of enumeration constants lined up in one line

Maximal number of enumeration constants lined up in one line

Specifies how many enumeration constants are lined up in one row.


Line up to 5 elements in one row:

enum Enum1 { ONE, TWO, THREE };         
                                        
enum Enum2 { ONE, TWO, THREE, FOUR, FIVE };
                                        
enum Enum3 {                            
    ONE, TWO, THREE, FOUR, FIVE, SIX, SEVEN,
    EIGHT, NINE, TEN                    
};                                      


Line up to 3 elements in one row:

enum Enum1 { ONE, TWO, THREE };         
                                        
enum Enum2 {                            
    ONE, TWO, THREE, FOUR, FIVE         
};                                      
                                        
enum Enum3 {                            
    ONE, TWO, THREE, FOUR, FIVE, SIX, SEVEN,
    EIGHT, NINE, TEN                    
};                                      

To line up all elements in one row use setting value infinite.
To line up no element in one row use setting value 0.


See also... See also: Brace style for general code (statements, arrays, initializers...)




Arrays

Maximal number of array initializer elements lined up in one line

Maximal number of array initializer elements lined up in one line

Specifies how many array initializer elements are lined up in one row.


Line up to 5 elements in one row:

int array1[] = { 1, 2, 3 };             
                                        
int array2[] = { 1, 2, 3, 4, 5 };       
                                        
int array3[] = {                        
    11, 12, 13, 14, 15, 16, 17, 18, 19, 20,
    21, 22, 23, 24, 25, 26, 27, 28, 29, 30
};                                      


Line up to 3 elements in one row:

int array1[] = { 1, 2, 3 };             
                                        
int array2[] = {                        
    1, 2, 3, 4, 5                       
};                                      
                                        
int array3[] = {                        
    11, 12, 13, 14, 15, 16, 17, 18, 19, 20,
    21, 22, 23, 24, 25, 26, 27, 28, 29, 30
};                                      

To line up all elements in one row use setting value infinite.
To line up no element in one row use setting value 0.


See also... See also: Brace style for general code (statements, arrays, initializers...)