        --------------------------------------------------
                CodeNarc - Size and Complexity Rules
        --------------------------------------------------

Size and Complexity Rules  ("<rulesets/size.xml>")
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


* {AbcComplexity} Rule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  Calculates the <ABC> metric for methods/classes and checks against configured threshold values.

  The <<maxMethodComplexity>> property holds the threshold value for the ABC complexity
  value (score) for each method. If this value is non-zero, a method with a complexity value greater than
  this value is considered a violation.

  The <<maxClassAverageMethodComplexity>> property holds the threshold value for the average ABC
  complexity value (score) for each class. If this value is non-zero, a class with an average complexity
  value greater than this value is considered a violation.

  This rule treats "closure fields" as methods. If a class field is initialized to a Closure (ClosureExpression),
  then that Closure is analyzed and checked just like a method.

*---------------------------------+----------------------------------------------------------------+------------------------+
| <<Property>>                    | <<Description>>                                                | <<Default Value>>      |
*---------------------------------+----------------------------------------------------------------+------------------------+
| maxMethodComplexity             | The maximum <ABC complexity> value (score) allowed for a single| 60                     |
|                                 | method (or "closure field"). If zero or <null>, then do not    |                        |
|                                 | check method-level complexity.                                 |                        |
*---------------------------------+----------------------------------------------------------------+------------------------+
| maxClassAverageMethodComplexity | The maximum <ABC complexity> value (score) allowed for a class,| 60                     |
|                                 | calculated as the average complexity of its methods or         |                        |
|                                 | "closure fields". If zero or <null>, then do not check         |                        |
|                                 | class-level complexity.                                        |                        |
*---------------------------------+----------------------------------------------------------------+------------------------+
| ignoreMethodNames               | Specifies one or more (comma-separated) method names that      | <<<null>>>             |
|                                 | that should not cause a rule violation. The names may          |                        |
|                                 | optionally contain wildcards (*,?). Note that the ignored      |                        |
|                                 | methods still contribute to the class complexity value.        |                        |
*---------------------------------+----------------------------------------------------------------+------------------------+

** ABC Size/Complexity Metric Calculation Rules
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  The <ABC complexity> value (score) is calculated as follows:
  The <ABC> metric measures size/complexity by counting the number of Assignments (A), Branches (B) and
  Conditions (C) and assigns a single numerical score calculated as:

  <<< |ABC| = sqrt((A*A)+(B*B)+(C*C)) >>>

  The <ABC Metric> calculation rules for Groovy:

  * Add one to the <assignment> count for each occurrence of an assignment operator, excluding constant
    declarations: = *= /= %= += <<= >>= &= |= ^= >>>=

  * Add one to the <assignment> count for each occurrence of an increment or decrement operator
    (prefix or postfix): ++ --

  * Add one to the <branch> count for each function call or class method call.

  * Add one to the <branch> count for each occurrence of the new operator.

  * Add one to the <condition> count for each use of a conditional operator: == != <= >= < > <=> =~ ==~

  * Add one to the <condition> count for each use of the following keywords: else case default try catch ?

  * Add one to the <condition> count for each unary conditional expression.

** Notes
~~~~~~~~~

  * See the {{{http://www.softwarerenovation.com/ABCMetric.pdf}ABC Metric specification}}

  * See the {{{http://jakescruggs.blogspot.com/2008/08/whats-good-flog-score.html}Blog post}} describing guidelines for interpreting an ABC score

  * See the {{{http://gmetrics.sourceforge.net/gmetrics-AbcMetric.html}GMetrics ABC metric}}.
    This includes a discussion of guidelines for interpreting <ABC> scores.

  * This rule requires Groovy 1.6 (or later).

  * This rule requires the GMetrics jar on the classpath. See {{{http://gmetrics.sourceforge.net/}GMetrics}}.


* {ClassSize} Rule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  Checks if the size of a class exceeds the number of lines specified by the <<maxLines>> property.

*---------------------+----------------------------------------------------------------+------------------------+
| <<Property>>        | <<Description>>                                                | <<Default Value>>      |
*---------------------+----------------------------------------------------------------+------------------------+
| maxLines            | The maximum number of lines allowed in a class definition.     | 1000                   |
*---------------------+----------------------------------------------------------------+------------------------+


* {CrapMetric} Rule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  Calculates the {{{http://www.artima.com/weblogs/viewpost.jsp?thread=210575}C.R.A.P.}} (Change Risk Anti-Patterns)
  metric score for methods/classes and checks against configured threshold values.

  The <CRAP> metric score is based on the <cyclomatic complexity> and test coverage for individual methods.
  A method with a <CRAP> value greater than the <<maxMethodCrapScore>> property causes a violation. Likewise,
  a class that has an (average method) <CRAP> value greater than the <<maxClassAverageMethodCrapScore>>
  property causes a violation.

  <<NOTE:>> This rule requires the <<GMetrics>>[3] jar, version 0.5 (or later), on the classpath, as well as
  a <<Cobertura>>[4]-[6] XML coverage file. If either of these prerequisites is not available, this rule
  logs a warning messages and exits (i.e., does nothing).

  The <<maxMethodCrapScore>> property holds the threshold value for the CRAP value for each method. If this
  value is non-zero, a method with a cyclomatic complexity value greater than this value is considered a violation.

 The <<maxClassAverageMethodCrapScore>> property holds the threshold value for the average CRAP value
 for each class. If this value is non-zero, a class with an average cyclomatic complexity
 value greater than this value is considered a violation.

 NOTE: This rule does NOT treat <closure fields> as methods (unlike some of the other size/complexity rules).

*---------------------------------+----------------------------------------------------------------+------------------------+
| <<Property>>                    | <<Description>>                                                | <<Default Value>>      |
*---------------------------------+----------------------------------------------------------------+------------------------+
| coberturaXmlFile                | The path to the Cobertura XML coverage file for the Groovy code| <<<null>>>             |
|                                 | By default, the path is relative to the classpath. But the path|                        |
|                                 | may be optionally prefixed by any of the valid java.net.URL    |                        |
|                                 | prefixes, such as "file:" (to load from a relative or absolute |                        |
|                                 | path on the filesystem), or "http:". This property is REQUIRED.|                        |
*---------------------------------+----------------------------------------------------------------+------------------------+
| maxMethodCrapScore              | The maximum <CRAP> metric value allowed for a single method.   | 30                     |
|                                 | If zero or <null>, then do not check method-level complexity.  |                        |
*---------------------------------+----------------------------------------------------------------+------------------------+
| maxClassAverageMethodCrapScore  | The maximum <CRAP> metric value allowed for a class,           | 30                     |
|                                 | calculated as the average CRAP value of its methods. If        |                        |
|                                 | zero or <null>, then do not check class-level CRAP value.        |                        |
*---------------------------------+----------------------------------------------------------------+------------------------+
| ignoreMethodNames               | Specifies one or more (comma-separated) method names that      | <<<null>>>             |
|                                 | that should not cause a rule violation. The names may          |                        |
|                                 | optionally contain wildcards (*,?). Note that the ignored      |                        |
|                                 | methods still contribute to the class complexity value.        |                        |
*---------------------------------+----------------------------------------------------------------+------------------------+

* CRAP Formula
~~~~~~~~~~~~~~~

  Given a Groovy method m, C.R.A.P. for m is calculated as follows:

+----------------------------------------------------------------------------------------
  C.R.A.P.(m) = comp(m)^2 * (1 - cov(m)/100)^3 + comp(m)
+----------------------------------------------------------------------------------------

  Where <<comp(m)>> is the <cyclomatic complexity> of method m, and <<cov(m)>> is the test code coverage provided
  by automated tests.


* References
~~~~~~~~~~~~

 * <<[1]>> The original 2007 {{{http://www.artima.com/weblogs/viewpost.jsp?thread=210575}blog post}} that defined the <<CRAP>> metric.

 * <<[2]>> A 2011 {{{http://googletesting.blogspot.com/2011/02/this-code-is-crap.html}blog post}} from Alberto Savoia
   (the co-creator of the <<CRAP>> metric with Bob Evans), describing the formula, the motivation, and the <<CRAP4J>>
   tool for calculating <<CRAP>> score for Java code.

 * <<[3]>> The {{{http://gmetrics.sourceforge.net/gmetrics-CrapMetric.html}GMetrics CRAP Metric}}.

 * <<[4]>> {{{http://cobertura.sourceforge.net/}Cobertura}} -- <Cobertura is a free Java tool that calculates the percentage
 of code accessed by tests. It can be used to identify which parts of your Java program are lacking test coverage.>

 * <<[5]>> {{{http://cobertura.sourceforge.net/anttaskreference.html}Cobertura Ant Task Reference}}

 * <<[6]>> {{{http://mojo.codehaus.org/cobertura-maven-plugin/index.html}Cobertura Maven Plugin}}



* {CyclomaticComplexity} Rule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  Calculates the <Cyclomatic Complexity> for methods/classes and checks against configured threshold values.

  The <<maxMethodComplexity>> property holds the threshold value for the cyclomatic complexity
 value for each method. If this value is non-zero, a method with a cyclomatic complexity value greater than
 this value is considered a violation.

 The <<maxClassAverageMethodComplexity>> property holds the threshold value for the average cyclomatic
 complexity value for each class. If this value is non-zero, a class with an average cyclomatic complexity
 value greater than this value is considered a violation.

 This rule treats "closure fields" as methods. If a class field is initialized to a Closure (ClosureExpression),
 then that Closure is analyzed and checked just like a method.

*---------------------------------+----------------------------------------------------------------+------------------------+
| <<Property>>                    | <<Description>>                                                | <<Default Value>>      |
*---------------------------------+----------------------------------------------------------------+------------------------+
| maxMethodComplexity             | The maximum <cyclomatic complexity> value allowed for a single | 20                     |
|                                 | method (or "closure field"). If zero or <null>, then do not    |                        |
|                                 | check method-level complexity.                                 |                        |
*---------------------------------+----------------------------------------------------------------+------------------------+
| maxClassAverageMethodComplexity | The maximum <cyclomatic complexity> value allowed for a class, | 20                     |
|                                 | calculated as the average complexity of its methods or         |                        |
|                                 | "closure fields". If zero or <null>, then do not check         |                        |
|                                 | class-level complexity.                                        |                        |
*---------------------------------+----------------------------------------------------------------+------------------------+
| ignoreMethodNames               | Specifies one or more (comma-separated) method names that      | <<<null>>>             |
|                                 | that should not cause a rule violation. The names may          |                        |
|                                 | optionally contain wildcards (*,?). Note that the ignored      |                        |
|                                 | methods still contribute to the class complexity value.        |                        |
*---------------------------------+----------------------------------------------------------------+------------------------+

** Cyclomatic Complexity Metric Calculation Rules
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  The <cyclomatic complexity> value is calculated as follows:

  <Start with a initial (default) value of one (1).
  Add one (1) for each occurrence of each of the following:>

     * <<<if>>> statement

     * <<<while>>> statement

     * <<<for>>> statement

     * <<<case>>> statement

     * <<<catch>>> statement

     * <<<&&>>> and <<<||>>> boolean operations

     * <<<?:>>> ternary operator and <<<?:>>> <Elvis> operator.

     * <<<?.>>> null-check operator

** Notes
~~~~~~~~~

  * See the {{{http://en.wikipedia.org/wiki/Cyclomatic_complexity}Cyclomatic Complexity Wikipedia entry}}

  * See the {{{http://www.literateprogramming.com/mccabe.pdf}original paper describing Cyclomatic Complexity}}

  * See the {{{http://gmetrics.sourceforge.net/gmetrics-CyclomaticComplexityMetric.html}GMetrics Cyclomatic Complexity metric}}.
    This includes a discussion of guidelines for interpreting <cyclomatic complexity> values.

  * This rule requires Groovy 1.6 (or later).

  * This rule requires the GMetrics jar on the classpath. See {{{http://gmetrics.sourceforge.net/}GMetrics}}.


* {MethodCount} Rule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  <Since CodeNarc 0.11>

  Checks if the number of methods within a class exceeds the number of lines specified by the <<maxMethod>> property.

  A class with too many methods is probably a good suspect for refactoring, in order to reduce its
  complexity and find a way to have more fine grained objects.

*---------------------+----------------------------------------------------------------+------------------------+
| <<Property>>        | <<Description>>                                                | <<Default Value>>      |
*---------------------+----------------------------------------------------------------+------------------------+
| maxMethods          | The maximum number of methods allowed in a class definition.   | 30                     |
*---------------------+----------------------------------------------------------------+------------------------+


* {MethodSize} Rule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  Checks if the size of a method exceeds the number of lines specified by the <<maxLines>> property.

*---------------------+----------------------------------------------------------------+------------------------+
| <<Property>>        | <<Description>>                                                | <<Default Value>>      |
*---------------------+----------------------------------------------------------------+------------------------+
| maxLines            | The maximum number of lines allowed in a method definition.    | 100                    |
*---------------------+----------------------------------------------------------------+------------------------+
| ignoreMethodNames   | Specifies one or more (comma-separated) method names that      | <<<null>>>             |
|                     | should be ignored (i.e., that should not cause a rule          |                        |
|                     | violation). The names may optionally contain wildcards (*,?).  |                        |
*---------------------+----------------------------------------------------------------+------------------------+


* {NestedBlockDepthRule} Rule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  Checks for blocks or closures nested more deeply than a configured maximum number.
  Blocks include <<<if>>>, <<<for>>>, <<<while>>>, <<<switch>>>, <<<try>>>, <<<catch>>>,
  <<<finally>>> and <<<synchronized>>> blocks/statements, as well as closures.

  Methods calls, constructor calls, and property access through Builder objects are ignore. For instance, this code
  does not cause a violation:

-------------------------------------------------------------------------------
    myBuilder.root {
        foo {
            bar {
                baz {
                    quix {
                        qux {
                            quaxz {
                            }
                        }
                    }
                }
            }
        }
    }
-------------------------------------------------------------------------------

*---------------------+-----------------------------------------------------------------+------------------------+
| <<Property>>        | <<Description>>                                                 | <<Default Value>>      |
*---------------------+-----------------------------------------------------------------+------------------------+
| maxNestedBlockDepth | The maximum number of nesting levels. A block or closure nested | 5                      |
|                     | deeper than that number of levels is considered a violation.    |                        |
*---------------------+-----------------------------------------------------------------+------------------------+
| ignoreRegex         | Determines what is a builder call. For instance, closures       | .*(b|B)uilder          |
|                     | nested on a method named createBuilder, a property named        |                        |
|                     | myBuilder, or a constructor call to object MyBuilder() do       |                        |
|                     | not produce violations.                                         |                        |
*---------------------+-----------------------------------------------------------------+------------------------+

