Title

title

5.6.1.9 Line Wrapping

Line Wrapping can be one of the most important parts of source code formatting. Depending on the used code conventions there are always a lot of options to wrap lines.
Jindent knows several algorithms to perform line wrapping and tries always to find the best fitting solution.
The line wrapping algorithms keep attention of operator precedence, prefer low level wrapping, and much more.

title

5.6.1.9.1 General

Enable line wrapping to fit source code to maximal line length

Enables or disables all line wrapping features.

Please note: If this setting is disabled then Jindent will not keep the line breaks from the original input source codes. Instead of that it will format all lines without caring about a maximal line length.

Maximal line length

Sets the maximal line length of all source code lines. If source code elements exceed this line length, then Jindent will wrap these elements to new lines.

For instance the input source code:

				int longName1 = (longName2 - longName3 - longName4) / (longName5 + longName6 + longName7);

will be wrapped if "Maximal line length" is set to 78:

				int longName1 = (longName2 - longName3 - longName4)                           |

				                / (longName5 + longName6 + longName7);                        |

In this case the line wrapping algorithm prefers to wrap before low level operator /. Additionally the wrapped line will be aligned correctly to its corresponding operand.

Line wrapping policy

Specifies which general line wrapping algorithm shall be used to wrap source code to a new line. Currently Jindent offers two algorithms:

Scope related, increase readability (default and recommended) - wraps and indents source code elements depending on their scope, meaning and brace level. Prefers high level before low level line wrapping to improve the readability of the source code.

Sample with scope related line wrapping policy:

				callALongMethodName(callMethodA(anArg, anotherArg),                             |

				                    callMethodB(anArg, anotherArg),                             |

				                    callMethodC(anArg, anotherArg),                             |

				                    callMethodD(anArg, anotherArg),                             |

				                    callMethodE(anArg, anotherArg),                             |

				                    callMethodF(anArg, anotherArg));                            |

Simple, save space - wraps source code elements only right before the maximum column size which means the algorithm does not take care about scopes or brace levels. To indent a wrapped line the alternative indentation setting is used. This line wrapping policy creates long lines to save space.

Sample with simple line wrapping policy:

				callALongMethodName(callMethodA(anArg, anotherArg), callMethodB(anArg,

				        anotherArg), callMethodC(anArg, anotherArg), callMethodD(anArg,

				        anotherArg), callMethodE(anArg, anotherArg), callMethodF(anArg,

				        anotherArg))                                        |

Wrap lines even if only comments exceed maximal line length

Wraps source code lines if just comments exceeds the maximal line length.

"Maximal line length" is set to 60 and we do not want Jindent to wrap lines just because of exceeding comments:

				public void method()                                        |

				{                                                           |

				    value = function(parameter1, parameter2);    // exceeding comment

				}                                                           |

One advantage in this case is that focus is kept on pure Java code with leaving comments aside.

The same example as above, but now we want Jindent to wrap lines because of exceeding comments:

				public void method()                                        |

				{                                                           |

				    value = function(parameter1,                            |

				                     parameter2);    // exceeding comment   |

				}                                                           |

Now the line wrapping is performed for all kind of tokens (even for comment tokens) which exceed maximal line length.

Alternative indentation

Sets an alternative indentation size value which is used by settings: "Maximal gap size of indentations" and "Avoid confusing indentations"
Generally we suggest to set this size to a value which is double "General indentation size"

Please refer to the next settings below to get to know more about "Alternative indentation"

Maximal gap size of indentations

Detects big gaps caused by line wrapping and reindents these source code lines again with a smaller alternative indentation size.

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

				public class MyClass {                                                |

				                                                                      |

				    void iKnowThisLooksStupidButItIsOnlyAnExample(Parameter one,      |

				                                                  Parameter two,      |

				                                                  Parameter three) {  |

				         firstLineOfCode();                                           |

				         ...                                                          |

				    }                                                                 |

				}                                                                     |

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

To handle this problem we introduce two gap size measures:

Gap size relative to current block indentation:

				public class MyClass {                                                |

				                                                                      |

				    void iKnowThisLooksStupidButItIsOnlyAnExample(Parameter one,      |

				    |---- gap size relative to block indent -----|Parameter two,

				                                                  Parameter three) {  |

				        firstLineOfCode();                                            |

				        ...                                                           |

				    }                                                                 |

				}                                                                     |

The gap size counter counts all white spaces from 'current indentation size' to first appearing token.

Absolute gap size, which is equivalent to: absolute column position

				public class MyClass {                                                |

				                                                                      |

				     void iKnowThisLooksStupidButItIsOnlyAnExample(Parameter one,     |

				|-------------- absolute gap size ----------------|Parameter two,

				                                                   Parameter three) { |

				        firstLineOfCode();                                            |

				        ...                                                           |

				    }                                                                 |

				}                                                                     |

The gap size counter counts all white spaces from 'first column' to first appearing token.

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: "Alternative indentation" to reindent this source code again.

An example explains the algorithm:

We assume setting "Alternative indentation" is set to 8.
Setting "Maximal gap size of indentations" is using a 'relative' detection mode for big gaps and the maximal allowed size of these gaps is 30.

Now Jindent would procced the following steps:

First Jindent would try to find big gaps:

				public class MyClass {                                                |

				                                                                      |

				    void iKnowThisLooksStupidButItIsOnlyAnExample(Parameter one,      |

				    |------ relative gap size: 46 spaces --------|Parameter two,

				                                                  Parameter three) {  |

				        firstLineOfCode();                                            |

				        ...                                                           |

				    }                                                                 |

				}                                                                     |

After findig the gap, Jindent uses the value from "Alternative indentation" and reindents the gap again (with 8 spaces in this case):

				public class MyClass {                                                |

				                                                                      |

				    void iKnowThisLooksStupidButItIsOnlyAnExample(Parameter one,      |

				    |------|Parameter two,                                            |

				            Parameter three) {                                        |

				        firstLineOfCode();                                            |

				        ...                                                           |

				    }                                                                 |

				}                                                                     |

The new indentation looks properly now and the big gap is gone.

Using 'absolute' detection mode to find big gaps works of course similiar. In this case the gap counter will start from first column to identify gaps.

Use setting infinite to leave all kind of gaps untouched.

Use setting 0 and Jindent will always use "Alternative indentation" to indent all kind of wrappings.