Skip to content

Commit

Permalink
doc: extend Indentation Check explanation of line wrap
Browse files Browse the repository at this point in the history
  • Loading branch information
@romani @rnveach
romani authored and rnveach committed Jan 19, 2020
1 parent 9a7a8e1 commit dd95725
Show file tree
Hide file tree
Showing 2 changed files with 207 additions and 9 deletions.
108 changes: 104 additions & 4 deletions src/main/java/com/puppycrawl/tools/checkstyle/checks/indentation/IndentationCheck.java
View file
Expand Up @@ -41,6 +41,31 @@
* case, this check should just ensure that a minimal set of indentation
* rules is followed.
* </p>
* <p>
* Basic offset indentation is used for indentation inside code blocks.
* For any lines that span more than 1, line wrapping indentation is used for those lines
* after the first. Brace adjustment, case, and throws indentations are all used only if
* those specific identifiers start the line. If, for example, a brace is used in the
* middle of the line, its indentation will not take effect. All indentations have an
* accumulative/recursive effect when they are triggered. If during a line wrapping, another
* code block is found and it doesn't end on that same line, then the subsequent lines
* afterwards, in that new code block, are increased on top of the line wrap and any
* indentations above it.
* </p>
* <p>
* Example:
* </p>
* <pre>
* if ((condition1 &amp;&amp; condition2)
* || (condition3 &amp;&amp; condition4) // line wrap with bigger indentation
* ||!(condition5 &amp;&amp; condition6)) { // line wrap with bigger indentation
* field.doSomething() // basic offset
* .doSomething() // line wrap
* .doSomething( c -&gt; { // line wrap
* return c.doSome(); // basic offset
* });
* }
* </pre>
* <ul>
* <li>
* Property {@code basicOffset} - Specify how far new indentation level should be
Expand Down Expand Up @@ -80,12 +105,45 @@
* </li>
* </ul>
* <p>
* To configure the check:
* To configure the check for default behavior:
* </p>
* <pre>
* &lt;module name="Indentation"/&gt;
* </pre>
* <p>
* Example of Compliant code for default configuration (in comment name of property
* that controls indentations):
* </p>
* <pre>
* class Test {
* String field; // basicOffset
* int[] arr = { // basicOffset
* 5, // arrayInitIndent
* 6 }; // arrayInitIndent
* void bar() throws Exception // basicOffset
* { // braceAdjustment
* foo(); // basicOffset
* } // braceAdjustment
* void foo() { // basicOffset
* if ((cond1 &amp;&amp; cond2) // basicOffset
* || (cond3 &amp;&amp; cond4) // lineWrappingIndentation, forceStrictCondition
* ||!(cond5 &amp;&amp; cond6)) { // lineWrappingIndentation, forceStrictCondition
* field.doSomething() // basicOffset
* .doSomething() // lineWrappingIndentation and forceStrictCondition
* .doSomething( c -&gt; { // lineWrappingIndentation and forceStrictCondition
* return c.doSome(); // basicOffset
* });
* }
* }
* void fooCase() // basicOffset
* throws Exception { // throwsIndent
* switch (field) { // basicOffset
* case "value" : bar(); // caseIndent
* }
* }
* }
* </pre>
* <p>
* To configure the check to enforce the indentation style recommended by Oracle:
* </p>
* <pre>
Expand All @@ -94,6 +152,17 @@
* &lt;/module&gt;
* </pre>
* <p>
* Example of Compliant code for default configuration (in comment name of property that controls
* indentation):
* </p>
* <pre>
* void fooCase() { // basicOffset
* switch (field) { // basicOffset
* case "value" : bar(); // caseIndent
* }
* }
* </pre>
* <p>
* To configure the Check to enforce strict condition in line-wrapping validation.
* </p>
* <pre>
Expand All @@ -102,18 +171,49 @@
* &lt;/module&gt;
* </pre>
* <p>
* Such config doesn't allow next cases:
* Such config doesn't allow next cases even code is aligned further to the right for better
* reading:
* </p>
* <pre>
* void foo(String aFooString,
* int aFooInt) {} // indent:8 ; expected: 4; warn, because 8 != 4
* int aFooInt) { // indent:8 ; expected: 4; violation, because 8 != 4
* if (cond1
* || cond2) {
* field.doSomething()
* .doSomething();
* }
* if ((cond1 &amp;&amp; cond2)
* || (cond3 &amp;&amp; cond4) // violation
* ||!(cond5 &amp;&amp; cond6)) { // violation
* field.doSomething()
* .doSomething() // violation
* .doSomething( c -&gt; { // violation
* return c.doSome();
* });
* }
* }
* </pre>
* <p>
* But if forceStrictCondition = false, this code is valid:
* </p>
* <pre>
* void foo(String aFooString,
* int aFooInt) {} // indent:8 ; expected: &gt; 4; ok, because 8 &gt; 4
* int aFooInt) { // indent:8 ; expected: &gt; 4; ok, because 8 &gt; 4
* if (cond1
* || cond2) {
* field.doSomething()
* .doSomething();
* }
* if ((cond1 &amp;&amp; cond2)
* || (cond3 &amp;&amp; cond4)
* ||!(cond5 &amp;&amp; cond6)) {
* field.doSomething()
* .doSomething()
* .doSomething( c -&gt; {
* return c.doSome();
* });
* }
* }
* </pre>
*
* @noinspection ThisEscapedInObjectConstruction
Expand Down
108 changes: 103 additions & 5 deletions src/xdocs/config_misc.xml
View file
Expand Up @@ -1084,6 +1084,30 @@ String unitAbbrev = "\u03bc\u03bc\u03bc";
times it is practical experience. In any case, this check should
just ensure that a minimal set of indentation rules is followed.
</p>
<p>
Basic offset indentation is used for indentation inside code blocks.
For any lines that span more than 1, line wrapping indentation is used for those
lines after the first.
Brace adjustment, case, and throws indentations are all used only if those specific
identifiers start the line. If, for example, a brace is used in the middle of the line,
its indentation will not take effect.
All indentations have an accumulative/recursive effect when they are triggered. If
during a line wrapping, another code block is found and it doesn't end on that same
line, then the subsequent lines afterwards, in that new code block, are increased on
top of the line wrap and any indentations above it.
</p>
<p>Example:</p>
<source>
if ((condition1 &amp;&amp; condition2)
|| (condition3 &amp;&amp; condition4) // line wrap with bigger indentation
||!(condition5 &amp;&amp; condition6)) { // line wrap with bigger indentation
field.doSomething() // basic offset
.doSomething() // line wrap
.doSomething( c -> { // line wrap
return c.doSome(); // basic offset
});
}
</source>
</subsection>

<subsection name="Properties" id="Indentation_Properties">
Expand Down Expand Up @@ -1157,12 +1181,44 @@ String unitAbbrev = "\u03bc\u03bc\u03bc";

<subsection name="Examples" id="Indentation_Examples">
<p>
To configure the check:
To configure the check for default behavior:
</p>
<source>
&lt;module name=&quot;Indentation&quot;/&gt;
</source>

<p>
Example of Compliant code for default configuration
(in comment name of property that controls indentations):
</p>
<source>
class Test {
String field; // basicOffset
int[] arr = { // basicOffset
5, // arrayInitIndent
6 }; // arrayInitIndent
void bar() throws Exception // basicOffset
{ // braceAdjustment
foo(); // basicOffset
} // braceAdjustment
void foo() { // basicOffset
if ((cond1 &amp;&amp; cond2) // basicOffset
|| (cond3 &amp;&amp; cond4) // lineWrappingIndentation, forceStrictCondition
||!(cond5 &amp;&amp; cond6)) { // lineWrappingIndentation, forceStrictCondition
field.doSomething() // basicOffset
.doSomething() // lineWrappingIndentation and forceStrictCondition
.doSomething( c -> { // lineWrappingIndentation and forceStrictCondition
return c.doSome(); // basicOffset
});
}
}
void fooCase() // basicOffset
throws Exception { // throwsIndent
switch (field) { // basicOffset
case "value" : bar(); // caseIndent
}
}
}
</source>
<p>
To configure the check to enforce the indentation style recommended by
Oracle:
Expand All @@ -1172,6 +1228,17 @@ String unitAbbrev = "\u03bc\u03bc\u03bc";
&lt;module name=&quot;Indentation&quot;&gt;
&lt;property name=&quot;caseIndent&quot; value=&quot;0&quot;/&gt;
&lt;/module&gt;
</source>
<p>
Example of Compliant code for default configuration
(in comment name of property that controls indentation):
</p>
<source>
void fooCase() { // basicOffset
switch (field) { // basicOffset
case "value" : bar(); // caseIndent
}
}
</source>
<p>
To configure the Check to enforce strict condition in line-wrapping validation.
Expand All @@ -1182,18 +1249,49 @@ String unitAbbrev = "\u03bc\u03bc\u03bc";
&lt;/module&gt;
</source>
<p>
Such config doesn't allow next cases:
Such config doesn't allow next cases
even code is aligned further to the right for better reading:
</p>
<source>
void foo(String aFooString,
int aFooInt) {} // indent:8 ; expected: 4; warn, because 8 != 4
int aFooInt) { // indent:8 ; expected: 4; violation, because 8 != 4
if (cond1
|| cond2) {
field.doSomething()
.doSomething();
}
if ((cond1 &amp;&amp; cond2)
|| (cond3 &amp;&amp; cond4) // violation
||!(cond5 &amp;&amp; cond6)) { // violation
field.doSomething()
.doSomething() // violation
.doSomething( c -> { // violation
return c.doSome();
});
}
}
</source>
<p>
But if forceStrictCondition = false, this code is valid:
</p>
<source>
void foo(String aFooString,
int aFooInt) {} // indent:8 ; expected: > 4; ok, because 8 > 4
int aFooInt) { // indent:8 ; expected: > 4; ok, because 8 > 4
if (cond1
|| cond2) {
field.doSomething()
.doSomething();
}
if ((cond1 &amp;&amp; cond2)
|| (cond3 &amp;&amp; cond4)
||!(cond5 &amp;&amp; cond6)) {
field.doSomething()
.doSomething()
.doSomething( c -> {
return c.doSome();
});
}
}
</source>
</subsection>

Expand Down

0 comments on commit dd95725

Please sign in to comment.