		--------------------------------------------------
					  GMetrics - ABC Metric
		--------------------------------------------------

ABC Metric
~~~~~~~~~~

 Calculates the <<ABC>> Metric for a class or method. <<ABC>> is a metric of
 size/complexity that counts 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))
-------------------------------------------------------------------------------

 Implemented by the <<<org.gmetrics.metric.abc.AbcMetric>>> class.

 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.
   These are cases where a single variable/field/value is treated as a boolean value.
   Examples include <<<if (x)>>> and <<<return !ready>>>.


* Additional notes
~~~~~~~~~~~~~~~~~~

 * A property access is treated like a method call (and thus increments the branch count).

 * If a class field is initialized to a Closure (ClosureExpression), then that Closure is
   analyzed just like a method.


* Guidelines for Interpreting ABC Metric Values
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  A frequently-referenced {{{http://jakescruggs.blogspot.com/2008/08/whats-good-flog-score.html}blog post}}
  by Jake Scruggs ([4]) offers the following guidelines for interpreting an <<ABC>> score. Note that these
  values refer to the score (magnitude) calculated for a single method:

    * 0-10 = <Awesome>

    * 11-20 = <Good enough>

    * 21-40 = <Might need refactoring>

    * 41-60 = <Possible to justify>

    * 61-100 = <Danger>

    * 100-200 = <Whoop, whoop, whoop>

    * 200 + = <Someone please think of the children>


* Metric Properties
~~~~~~~~~~~~~~~~~~~

  The following properties can be configured for this metric within a <MetricSet>. See
  {{{./gmetrics-creating-metricset.html}Creating a MetricSet}} for information on the syntax of
  setting a metric property.

*-----------------+--------------------------------------------------------------------+------------------------+
| <<Property>>    | <<Description>>                                                    | <<Default Value>>      |
*-----------------+--------------------------------------------------------------------+------------------------+
| enabled         | This <<<boolean>>> property controls whether the metric is         | <<<true>>>             |
|                 | <enabled>. If set to <<<false>>>, then the metric is not included  |                        |
|                 | as part of the results or the output reports.                      |                        |
*-----------------+--------------------------------------------------------------------+------------------------+
| functions       | This <<<List\<String\>>>> property contains the names of the functions| <<<["total","average"]>>>|
|                 | to be calculated at the <method>, <class> and <package> levels     |                        |
|                 | and (potentially) included within the report(s). Valid values are: |                        |
|                 |    - "total"                                                       |                        |
|                 |    - "average"                                                     |                        |
|                 |    - "minimum"                                                     |                        |
|                 |    - "maximum"                                                     |                        |
*-----------------+--------------------------------------------------------------------+------------------------+
| includeClosureFields | This <<<boolean>>> property controls whether metric values are| <<<true>>>             |
|                 | calculated for <Closure Fields> and treated as <methods>. A        |                        |
|                 | <Closure Field> is a field that is initialized to a <Closure Expression>, |                 |
|                 | e.g., <<<def myField = \{ println 12 \}>>>.                        |                        |
*-----------------+--------------------------------------------------------------------+------------------------+


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

 * <<[1]>> The {{{http://www.softwarerenovation.com/ABCMetric.pdf}ABC Metric specification}}.

 * <<[2]>> The {{{http://c2.com/cgi/wiki?AbcMetric}The C2 Wiki page}} for the ABC Metric.

 * <<[3]>> {{{http://ruby.sadi.st/Flog.html}Flog}} is the popular Ruby tool that uses ABC.

 * <<[4]>> {{{http://jakescruggs.blogspot.com/2008/08/whats-good-flog-score.html}This blog post}}
   describes some guidelines for interpreting the ABC score. The post refers to the
   <<Flog>> tool, but the <<ABC>> score is calculated similarly (though adapted
   somewhat to account for language specifics) and the guidelines should be transferable.

