codenarc-rules-convention.apt

        --------------------------------------------------
                      CodeNarc - Convention Rules
        --------------------------------------------------

Convention Rules  ("<rulesets/convention.xml>")
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


* {ConfusingTernary} Rule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  <Since CodeNarc 0.12>

  In a ternary expression avoid negation in the test. For example, rephrase:
  <<<(x != y) ? diff : same>>> as: <<<(x == y) ? same : diff>>>. Consistent use of this rule makes the code easier to read.
  Also, this resolves trivial ordering problems, such as "does the error case go first?" or "does the common case go first?".

  Example:

-------------------------------------------------------------------------------
    (x != y) ? diff : same      // triggers violation
    (!x) ? diff : same          // triggers violation

    (x == y) ? same : diff      // OK
    (x) ? same : diff           // OK

    // this is OK, because of GroovyTruth there is no inverse of != null
    (x != null) ? diff : same

    // this is OK, because of GroovyTruth there is no inverse of != true
    (x != true) ? diff : same

    // this is OK, because of GroovyTruth there is no inverse of != false
    (x != false) ? diff : same
-------------------------------------------------------------------------------


* {CouldBeElvis} Rule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  <Since CodeNarc 0.15>

  Catch an if block that could be written as an elvis expression.

  Example of violations:

-------------------------------------------------------------------------------
    if (!x) {                   // violation
        x = 'some value'
    }

    if (!x)                     // violation
        x = "some value"

    if (!params.max) {          // violation
      params.max = 10
    }

    x ?: 'some value'           // OK
-------------------------------------------------------------------------------


* {CouldBeSwitchStatement} Rule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  <Since CodeNarc 1.0>

  Checks for three of more if statements that could be converted to a switch. Only applies to equality and instanceof.

  Example of violations:

-------------------------------------------------------------------------------
    if (x == 1) {                       // violation
       y = x
    } else if (x == 2) {
       y = x * 2
    } else if (x == 3) {
       y = x * 3
    } else {
       y = 0
    }

    if (y instanceof Integer) {         // violation
       x = y + 1
    }
    if (y instanceof String) {
       x = y + '1'
    } else if (y instanceof Boolean) {
       x = !y
    } else {
       x = null
    }

    if (x == 1) {                       // OK
        y = x
    }
    if (x == 2) {
        y = x * 2
    } else {
        y = 0
    }

    if (!x && y) {                      // OK
        doSomething()
    } else if (!x && z) {
        doSomethingElse()
    } else if (!x && i) {
        doAnotherThing()
    }

-------------------------------------------------------------------------------


* {HashtableIsObsolete} Rule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  <Since CodeNarc 0.17>

  Checks for references to the (<effectively>) obsolete <<<java.util.Hashtable>>> class.
  Use the <<Java Collections Framework>> classes instead, including <<<HashMap>>> or
  <<<ConcurrentHashMap>>>. See the JDK javadoc.

  Example of violations:

-------------------------------------------------------------------------------
    def myMap = new Hashtable()           // violation
-------------------------------------------------------------------------------


* {IfStatementCouldBeTernary} Rule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  <Since CodeNarc 0.18>

  Checks for:

  * An <<<if>>> statement where both the <<<if>>> and <<<else>>> blocks contain only a single <<<return>>>
    statement returning a constant or literal value.

  * A block where the second-to-last statement in a block is an <<<if>>> statement with no <<<else>>>, where
    the block contains a single <<<return>>> statement, and the last statement in the block is a <<<return>>>
    statement, and both <<<return>>> statements return a constant or literal value.
    This check is disabled by setting <<<checkLastStatementImplicitElse>>> to <<<false>>>.

  Example of violations:

-------------------------------------------------------------------------------
    if (condition) { return 44 } else { return 'yes' }                  // violation
    if (check()) { return [1, 2] } else { return "count=$count" }       // violation

    if (condition)                                                      // violation
        return null
    else return [a:1]

    def method1() {
        if (condition) {                                                // violation
            return 44
        }
        return 'yes'
    }
-------------------------------------------------------------------------------


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

  An inverted <if-else> statement is one in which there is a single <<<if>>> statement with a single
  <<<else>>> branch and the boolean test of the <<<if>>> is negated. For instance <<<if (!x) false else true>>>.
  It is usually clearer to write this as <<<if (x) true else false>>>.


* {LongLiteralWithLowerCaseL} Rule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  <Since CodeNarc 0.16>

  In Java and Groovy, you can specify long literals with the L or l character,
  for instance 55L or 24l. It is best practice to always use an uppercase L and never
  a lowercase l. This is because 11l rendered in some fonts may look like 111 instead of 11L.

  Example of violations:

-------------------------------------------------------------------------------
    def x = 1l
    def y = 55l
-------------------------------------------------------------------------------


* {NoDef} Rule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  <Since CodeNarc 0.22>

  Do not allow using the <<<def>>> keyword in code. Use a specific type instead.

*-------------------------------+----------------------------------------------------------------+---------------------+
| <<Property>>                  | <<Description>>                                                | <<Default Value>>   |
*-------------------------------+----------------------------------------------------------------+---------------------+
| excludeRegex                  | Regular expression describing names of attributes, parameters  | <<<>>>              |
|                               | or methods that could be precede by the <<<def>>> keyword.     |                     |
*-------------------------------+----------------------------------------------------------------+---------------------+


* {NoTabCharacter} Rule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  <Since CodeNarc 0.25>

  Checks that all source files do not contain the tab character.

  NOTE: This is a file-based rule, rather than an AST-based rule, so the <applyToClassNames> and
  <doNotApplyToClassNames> rule configuration properties are not available. See
  {{{./codenarc-configuring-rules.html#Standard_Properties_for_Configuring_Rules}
    Standard Properties for Configuring Rules}}.


* {ParameterReassignment} Rule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  <Since CodeNarc 0.17>

  Checks for a method or closure parameter being reassigned to a new value within the body of the method/closure,
  which is a confusing and questionable practice. Use a temporary variable instead.

  Example of violations:

-------------------------------------------------------------------------------
    void myMethod(int a, String b) {
        println a
        b = 'new value'     // violation
    }

    def myClosure1 = { int a, b ->
        a = 123             // violation
    }
-------------------------------------------------------------------------------


* {TernaryCouldBeElvis} Rule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  <Since CodeNarc 0.17>

  Checks for ternary expressions where the <boolean> and <true> expressions are the same.
  These can be simplified to an <Elvis> expression.

  Example of violations:

-------------------------------------------------------------------------------
    x ? x : false               // violation; can simplify to x ?: false

    foo() ? foo() : bar()       // violation; can simplify to foo() ?: bar()
    foo(1) ? foo(1) : 123       // violation; can simplify to foo(1) ?: 123

    (x == y) ? same : diff      // OK
    x ? y : z                   // OK
    x ? x + 1 : x + 2           // OK
    x ? 1 : 0                   // OK
    x ? !x : x                  // OK
    !x ? x : null               // OK

    foo() ? bar() : 123         // OK
    foo() ? foo(99) : 123       // OK
    foo(x) ? foo() : 123        // OK
    foo(1) ? foo(2) : 123       // OK
-------------------------------------------------------------------------------

  NOTE: If the <boolean> and <true> expressions are the same method call, and that method
  call has <side-effects>, then converting it to a <Elvis> expression may produce <different>
  behavior. The method will only be called <once>, rather than <twice>. But relying on those
  <side-effects> as part of a ternary expression behavior is confusing, error-prone and just a
  bad idea. In any case, that code should be refactored to move the reliance on the side-effects
  out of the ternary expression.

* {TrailingComma} Rule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  <Since CodeNarc 0.25>

  Check whether list and map literals contain optional trailing comma.
  Rationale: Putting this comma in make is easier
  to change the order of the elements or add new elements on the end.

*--------------------+---------------------------------------------------------------------+---------------------+
| <<Property>>       | <<Description>>                                                     | <<Default Value>>   |
*--------------------+---------------------------------------------------------------------+---------------------+
| checkList          | To disable checking List literals, set this property to <<<false>>> | <<<true>>>          |
*--------------------+---------------------------------------------------------------------+---------------------+
| checkMap           | To disable checking Map literals, set this property to <<<false>>>  | <<<true>>>          |
*--------------------+---------------------------------------------------------------------+---------------------+

  This is valid code:

-------------------------------------------------------------------------------
  int[] array1 = [] // one line declaration
  int[] array2 = [ // empty list
                 ]
  int[] array3 = [1,2,3] // one line declaration
  int[] array4 = [1,
                  2,
                  3, // contains trailing comma
                 ]
-------------------------------------------------------------------------------

  Example of violations:

-------------------------------------------------------------------------------
  int[] array2 = [1,
                  2 // there is no trailing comma
                 ]
-------------------------------------------------------------------------------

* {VectorIsObsolete} Rule
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  <Since CodeNarc 0.17>

  Checks for references to the (<effectively>) obsolete <<<java.util.Vector>>> class.
  Use the <<Java Collections Framework>> classes instead, including <<<ArrayList>>> or
  <<<Collections.synchronizedList()>>>. See the JDK javadoc.

  Example of violations:

-------------------------------------------------------------------------------
    def myList = new Vector()           // violation
-------------------------------------------------------------------------------