header icons

Documentation Rules


Rules are mapped to good and bad practices, as defined by the open-source community. They are computed by open-source rule-checking tools like PMD or FindBugs. They are classified by category associated to some quality characteristics.



  • Avoid Deeply Nested If Statements ( AvoidDeeplyNestedIfStmts ) provided by PMD Design Rules 5.1.2

    Avoid creating deeply nested if-then statements since they are harder to read and error-prone to maintain. The nesting threshold can be configured by the user, default value is 3.

    This rule impacts analysability, since deeply nested control structure are hard to understand past a given threshold. It also impacts changeability, since a maintainer will need to check the whole structure to apply a change. It also impacts testability, since it increases the number of paths to check.

  • Avoid Reassigning Parameters ( AvoidReassigningParameters ) provided by PMD Design Rules 5.1.2

    Reassigning values to incoming parameters is not recommended. Use temporary local variables instead.

    This rule impacts changeability, since the maintainer may assume that the parameters contain the passed values.

  • Bad Comparison ( BadComparison ) provided by PMD Design Rules 5.1.2

    Avoid equality comparisons with Double.NaN. Due to the implicit lack of representation precision when comparing floating point numbers these are likely to cause logic errors.

    This rule impacts reliability, since the comparison may produce unpredictable behaviour because of the floating precision.

  • Class With Only Private Constructors Should Be Final ( ClassWithOnlyPrivateConstructorsShouldBeFinal ) provided by PMD Design Rules 5.1.2

    A class with only private constructors should be final, unless the private constructor is invoked by a inner class.

    This rule impacts analysability, since the maintainer will have trouble understanding the intent of the class.

  • Close Resource ( CloseResource ) provided by PMD Design Rules 5.1.2

    Ensure that resources (like Connection, Statement, and ResultSet objects) are always closed after use.

    Makes sure you close your database connections. It does this by looking for code patterned like this: Connection c = X; try { // do stuff, and maybe catch something } finally { c.close(); }

    This rule impacts resources usage, since unneeded open connections take some memory and cpu.

  • Confusing Ternary ( ConfusingTernary ) provided by PMD Design Rules 5.1.2

    Avoid negation within an 'if' expression with an 'else' clause. For example, rephrase: if (x != y) diff(); else same(); as: if (x == y) same(); else diff(); Most 'if (x != y)' cases without an 'else' are often return cases, so 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?'.

    This rule impacts analysability.

  • Constructor Calls Overridable Method ( ConstructorCallsOverridableMethod ) provided by PMD Design Rules 5.1.2

    Calling overridable methods during construction poses a risk of invoking methods on an incompletely constructed object and can be difficult to debug. It may leave the sub-class unable to construct its superclass or forced to replicate the construction process completely within itself, losing the ability to call super(). If the default constructor contains a call to an overridable method, the subclass may be completely uninstantiable. Note that this includes method calls throughout the control flow graph - i.e., if a constructor Foo() calls a private method bar() that calls a public method buz(), this denotes a problem.

    Searches through all methods and constructors called from constructors. It marks as dangerous any call to overridable methods from non-private constructors. It marks as dangerous any calls to dangerous private constructors from non-private constructors.

    This rule impacts reliability, since the object may not be fully initialised. It may throw exceptions or cause an unpredictable behaviour.

  • God Class ( GodClass ) provided by PMD Design Rules 5.1.2

    The God Class rule detects the God Class design flaw using metrics. God classes do too many things, are very big and overly complex. They should be split apart to be more object-oriented. The rule uses the detection strategy described in 'Object-Oriented Metrics in Practice'. The violations are reported against the entire class. See also the references: Michele Lanza and Radu Marinescu. Object-Oriented Metrics in Practice: Using Software Metrics to Characterize, Evaluate, and Improve the Design of Object-Oriented Systems. Springer, Berlin, 1 edition, October 2006. Page 80.

    This rule impacts analysability, since an overly complex class is difficult to read. It also impact changeability, since separating the various fonctionalities of the class may be difficult.

  • Missing Break In Switch ( MissingBreakInSwitch ) provided by PMD Design Rules 5.1.2

    Switch statements without break or return statements for each case option may indicate problematic behaviour. Empty cases are ignored as these indicate an intentional fall-through.

    This rule impacts reliability, since an unpredictable behaviour may arise when unintendedly falling through the next case. It also impacts changeability, since introducing a new case may modify the behaviour of the previous one.

  • Non Case Label In Switch Statement ( NonCaseLabelInSwitchStatement ) provided by PMD Design Rules 5.1.2

    A non-case label (e.g. a named break/continue label) was present in a switch statement. This is legal, but confusing. It is easy to mix up the case labels and the non-case labels.

    This rule impacts analysability, since this may confuse the maintainer when reading the switch. By the way, introducing a label in the switch creates an intricate control flow and is discouraged.

  • Non Static Initializer ( NonStaticInitializer ) provided by PMD Design Rules 5.1.2

    A non-static initializer block will be called any time a constructor is invoked (just prior to invoking the constructor). While this is a valid language construct, it is rarely used and is confusing.

    This rule impacts analysability, since a maintainer will look for the constructor as the first chunk of code executed.

  • Non Thread Safe Singleton ( NonThreadSafeSingleton ) provided by PMD Design Rules 5.1.2

    Non-thread safe singletons can result in bad state changes. Eliminate static singletons if possible by instantiating the object directly. Static singletons are usually not needed as only a single instance exists anyway. Other possible fixes are to synchronize the entire method or to use an initialize-on-demand holder class (do not use the double-check idiom). See Effective Java, item 48.

    This rule impacts reliability, since bad state changes may induce an unpredictable behaviour.

  • Position Literals First In Case Insensitive Comparisons ( PositionLiteralsFirstInCaseInsensitiveComparisons ) provided by PMD Design Rules 5.1.2

    Position literals first in comparisons, if the second argument is null then NullPointerExceptions can be avoided, they will just return false.

    This rule impacts reliability, since a NullPointerException will arise if the object is null.

  • Position Literals First In Comparisons ( PositionLiteralsFirstInComparisons ) provided by PMD Design Rules 5.1.2

    Position literals first in comparisons, if the second argument is null then NullPointerExceptions can be avoided, they will just return false.

    This rule impacts reliability, since a NullPointerException will arise if the object is null.

  • Preserve Stack Trace ( PreserveStackTrace ) provided by PMD Design Rules 5.1.2

    Throwing a new exception from a catch block without passing the original exception into the new exception will cause the original stack trace to be lost making it difficult to debug effectively.

    This rule impacts analysability, since the original exception trace is lost.

  • Switch Statements Should Have Default ( SwitchStmtsShouldHaveDefault ) provided by PMD Design Rules 5.1.2

    All switch statements should include a default option to catch any unspecified values.

    This rule impacts reliability, since an unpredictable behaviour may result if the switch value was not intended.