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

previous topic  Previous:  Method/Constructor Next:  Enum   next topic

title
5.6.1.3.3 General

Brace style for general Java code (statements, arrays, initializers...)

Brace style for general Java code (statements, arrays, initializers...)

Left brace { new line


Controls whether the left brace of arrays, annotations and statements appears in a new line or not.


Setting left brace to a new line:

while (a < 10)                          
{                                       
    ...                                 


Do not set left brace to a new line:

while (a < 10) {                        
    ...                                 



Right brace } new line


Controls whether the right brace of if-else or do-while statements appears in a new line or not.
For all other statements, arrays and annotations this setting has no effect.


Setting right brace to a new line:

if (a < 10)                             
{                                       
    ...                                 
}                                       
else                                    
{                                       
    ...                                 
}                                       
                                        
do                                      
{                                       
    ...                                 
}                                       
while (a < 10);                         


Do not set right brace to a new line:

if (a < 10)                             
{                                       
    ...                                 
} else                                  
{                                       
    ...                                 
}                                       
                                        
do                                      
{                                       
    ...                                 
} while (a < 10);                       



Indent left brace {


Specifies the indentation size of left braces.


Setting left brace to a new line and using an indentation size of 4:

while·(a·<·10)                          
····{                                   
····...                                 


Setting left brace to a new line and using an indentation size of 0:

while·(a·<·10)                          
{                                       
    ...                                 


Do not set left brace to a new line and use indentation size of 1:

while·(a·<·10)·{                        
    ...                                 


Do not set left brace to a new line and use indentation size of 0:

while·(a·<·10){                         
    ...                                 



Indent right brace }


Specifies the indentation size of right braces.


Left brace is on a new line and set indentation size of 4 for left and right braces:

while·(a·<·10)                          
····{                                   
····...                                 
····}                                   


Left brace is on a new line and set indentation size of 0 for left and right braces:

while·(a·<·10)                          
{                                       
····...                                 
}                                       



Indent after right brace }


Controls indentation of right braces in if-else and do-while statements.
For all other statements, arrays and annotations this setting has no effect.


Do not set right brace to a new line and use an indentation size of 0:

if (a < 10)                             
{                                       
    ...                                 
}else                                   
{                                       
    ...                                 
}                                       
                                        
do                                      
{                                       
    ...                                 
}while (a < 10);                        


Do not set right brace to a new line and use an indentation size of 1:

if (a < 10)                             
{                                       
    ...                                 
} else                                  
{                                       
    ...                                 
}                                       
                                        
do                                      
{                                       
    ...                                 
} while (a < 10);                       



Cuddle braces of empty blocks {}


Specifies how to format braces of empty statement/annotation/array blocks.


Cuddle braces of empty blocks:

while (condition) {}                    


Do not cuddle braces of empty blocks:

while (condition) {                     
}                                       



Indent cuddled braces {}


Controls the indentation size of cuddled braces.


Cuddle braces of empty blocks and use an indentation of 0:

while·(condition){}                     


Cuddle braces of empty blocks and use an indentation of 1:

while·(condition)·{}                    



Prohibit blank lines after left brace {


Prohibits blank lines directly after a left brace of statement/array/annotation blocks.

Some code conventions require a blank line before each comment.
Such a formatting looks proper if the comment, for instance, appears between two statements.
But if a comment follows directly after a left brace of statement/array/annotation blocks an unecessary gap can appear.


Left brace of statement block is set to a new line using an indentation size of 0.
Additionally a blank line shall be inserted before comments:

while (a < 10)                          
{                                       
                                       
    // comment with a preceding blank line
    callAnotherMethod();                
                                       
    // another comment                  
    ...                                 
}                                       


In the example above the left brace and blank line before the comment seem to create an unnecessary gap.
To avoid such a gap just prohibit blank lines after left braces:

while (a < 10)                          
{                                       
    // comment with a preceding blank line
    callAnotherMethod();                
                                       
    // another comment                  
    ...                                 
}                                       

Now the blank line before the first comment disappeared and closed the gap, but all other comments still contain the expected blank line as usual.
Of course this works for all kind of blank lines and not only for blank lines before comments.

See also... See also: Jindent - Settings - Formatter - Java / SQLJ - Comments - Blank Lines , Jindent - Settings - Formatter - Java / SQLJ - Blank Lines




If number of lines in body is at least ... then insert blank line after {


Inserts an extra blank line after left braces of statements/arrays/annotations containing a certain number of lines in their bodies.

Code conventions which prefer the K&R brace style (also known as Kernal, Java or Sun Style: do NOT put left brace to a new line) can run into a specific issue regarding readability of source code.


Let's assume the following source code example is formatted in a typical K&R brace style:

while (a < 10) {                        
    callMethod(--a);                    
}                                       
                                       
for (int i = 0; i < 10; i++) {          
    callMethodA(i);                     
    for (int i = 0; i < n; i++) {       
        callMethodB(i);                 
        callMethodC(i);                 
    }                                   
    callMethodD(i);                     
}                                       
                                       
if (x == 0) {                           
    callMethodA();                      
    callMethodB();                      
} else {                                
    callMethodC();                      
    callMethodD();                      
}                                       

In this case formatting of statement while(a < 10) looks fine, but statement for (int i = 0; ...) { seems to be formatted too close: The statement head for (int i = 0; i < 10; i++) { and the first block statement callMethodA(i); are connected too close and could cause confusion.
To avoid a too close formatting for specific statements/arrays/annotations use setting "If number of lines in body is at least ... then insert blank line after {" to insert an extra blank line before the first block statement.


The same example as above, but now using setting "If number of lines in body is at least ... then insert blank line after {" with a value of 2.

while (a < 10) {                        
    callMethod(--a);                    
}                                       
                                       
for (int i = 0; i < 10; i++) {          
                                       
    callMethodA(i);                     
    for (int i = 0; i < n; i++) {       
                                       
        callMethodB(i);                 
        callMethodC(i);                 
    }                                   
    callMethodD(i);                     
}                                       
                                       
if (x == 0) {                           
                                       
    callMethodA();                      
    callMethodB();                      
} else {                                
                                       
    callMethodC();                      
    callMethodD();                      
}                                       

Now formatting of statement for (int i = 0; ...) { seems to be much clearer and statement while (a < 10) { is still formatted as before.
This setting counts the lines of code in every statement/array/annotation body and if at least 2 lines are counted then an extra blank line is inserted after the left brace of statement/array/annotation head.
With this setting typical small loop statements can be kept compact, but statements/arrays/annotations with an extended body are formatted more spacious and clearer.


The same example again, but ""If number of lines in body is at least ... then insert blank line after {"" is set to value 3.

while (a < 10) {                        
    callMethod(--a);                    
}                                       
                                       
for (int i = 0; i < 10; i++) {          
                                       
    callMethodA(i);                     
    for (int i = 0; i < n; i++) {       
        callMethodB(i);                 
        callMethodC(i);                 
    }                                   
    callMethodD(i);                     
}                                       
                                       
if (x == 0) {                           
    callMethodA();                      
    callMethodB();                      
} else {                                
    callMethodC();                      
    callMethodD();                      
}                                       

Now statement if (x == 0) { is formatted in the same way as while (a < 10) {.


Using value 0:

while (a < 10) {                        
                                       
    callMethod(--a);                    
}                                       
                                       
for (int i = 0; i < 10; i++) {          
                                       
    callMethodA(i);                     
    for (int i = 0; i < n; i++) {       
                                       
        callMethodB(i);                 
        callMethodC(i);                 
    }                                   
    callMethodD(i);                     
}                                       
                                       
if (x == 0) {                           
                                       
    callMethodA();                      
    callMethodB();                      
} else {                                
                                       
    callMethodC();                      
    callMethodD();                      
}                                       

And all statements are formatted more spacious.

To turn this setting completely off just choose value infinite.



If number of lines in body is at least ... then insert blank line before }


Inserts an extra blank line before right braces of statements/annotations/arrays containing a certain number of lines in their bodies.

This setting works exactly in the same way as "If number of lines in body is at least ... then insert blank line after {", but now the extra blank line will be inserted at the end of statement/annotation/array bodies.


Let's assume "If number of lines in body is at least ... then insert blank line after {" is set to 2 and "If number of lines in body is at least ... then insert blank line before }" is set to 2 too:

while (a < 10) {                        
    callMethod(--a);                    
}                                       
                                       
for (int i = 0; i < 10; i++) {          
                                       
    callMethodA(i);                     
    for (int i = 0; i < n; i++) {       
                                       
        callMethodB(i);                 
        callMethodC(i);                 
                                       
    }                                   
    callMethodD(i);                     
                                       
}                                       
                                       
if (x == 0) {                           
                                       
    callMethodA();                      
    callMethodB();                      
                                       
} else {                                
                                       
    callMethodC();                      
    callMethodD();                      
                                       
}                                       

This setting creates an even more spacious formatting style.



Do not insert blank line before single left brace


This setting is related to the previous setting: "If number of lines in body is at least ... then insert blank line before }"
If insertion of an extra blank line before right braces is used, then this setting prohibits this extra blank line insertion before single right braces. A single right brace is a brace which appears in a single line without any other token:


while (a < 10) {                        
    callMethod(--a);                    
}                    // <- this right brace appears alone
                                       
if (a < 10) {                           
    callMethodA();                      
    callMethodB();                      
} else {             // <- this right brace does not appear alone
    callMethodC();                      
    callMethodC();                      
}                    // <- this right brace appears alone

The code example above shows that the right brace of } else { does not appear alone, it is directly followed by an else token.

Now the next code example shows the usage of this setting:


Let's recall the example from the previous setting section. There we assumed "If number of lines in body is at least ... then insert blank line after {" and "If number of lines in body is at least ... then insert blank line before }" are set to value 2.

while (a < 10) {                        
    callMethod(--a);                    
}                                       
                                       
for (int i = 0; i < 10; i++) {          
                                       
    callMethodA(i);                     
    for (int i = 0; i < n; i++) {       
                                       
        callMethodB(i);                 
        callMethodC(i);                 
                                       
    }                                   
    callMethodD(i);                     
                                       
}                                       
                                       
if (x == 0) {                           
                                       
    callMethodA();                      
    callMethodB();                      
                                       
} else {                                
                                       
    callMethodC();                      
    callMethodD();                      
                                       
}                                       

Actually this already looks nice spacious for if-else statements, but for all other statements the extra blank lines before the right braces seems to be unnecessary.


Now we additionally use setting: "Do not insert blank line before single left brace" and prohibit extra blank lines before single right braces:

while (a < 10) {                        
    callMethod(--a);                    
}                                       
                                       
for (int i = 0; i < 10; i++) {          
                                       
    callMethodA(i);                     
    for (int i = 0; i < n; i++) {       
                                       
        callMethodB(i);                 
        callMethodC(i);                 
    }                                   
    callMethodD(i);                     
}                                       
                                       
if (x == 0) {                           
                                       
    callMethodA();                      
    callMethodB();                      
                                       
} else {                                
                                       
    callMethodC();                      
    callMethodD();                      
}                                       

Now the extra blank line was only inserted before } else { because this is the only case a right brace does not appear as a single brace.

So we finally have a well formatted output where no uncessary extra blank lines extend the source code.




See also... See also: Jindent - Settings - Formatter - Java / SQLJ - Braces Style - Presets , Space before left braces of array initializers