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 Branching Statement As Last In Loop ( AvoidBranchingStatementAsLastInLoop ) provided by PMD Basic Rules 5.1.2

    Using a branching statement as the last part of a loop may be a bug, and/or is confusing. Ensure that the usage is not a bug, or consider using another approach.

    This pattern impacts analysability, since the maintainer will have trouble understanding the intended behaviour.

  • Avoid Decimal Literals In BigDecimal Constructor ( AvoidDecimalLiteralsInBigDecimalConstructor ) provided by PMD Basic Rules 5.1.2

    One might assume that the result of 'new BigDecimal(0.1)' is exactly equal to 0.1, but it is actually equal to .1000000000000000055511151231257827021181583404541015625. This is because 0.1 cannot be represented exactly as a double (or as a binary fraction of any finite length). Thus, the long value that is being passed in to the constructor is not exactly equal to 0.1, appearances notwithstanding. The (String) constructor, on the other hand, is perfectly predictable: 'new BigDecimal('0.1')' is exactly equal to 0.1, as one would expect. Therefore, it is generally recommended that the (String) constructor be used in preference to this one.

    This rule impacts product reliability, since the actual number is not the one intended and precision errors may arise.

  • Avoid Multiple Unary Operators ( AvoidMultipleUnaryOperators ) provided by PMD Basic Rules 5.1.2

    The use of multiple unary operators may be problematic, and/or confusing. Ensure that the intended usage is not a bug, or consider simplifying the expression.

    This rule impacts the reliability, since the pattern has a good probability to be a bug. It also impacts analysability, since such unary operators are unnecessarily complex to understand.

  • Avoid Using Hard Coded IP ( AvoidUsingHardCodedIP ) provided by PMD Basic Rules 5.1.2

    Application with hard-coded IP addresses can become impossible to deploy in some cases. Externalizing IP adresses is preferable.

    This pattern impacts changeability, since it is easier to change the IP in an externalised configuration file. It also impacts reusability, since the hard coded IP address may not be adapted to a different usage. It also impacts portability since the hard coded IP address may not be adapted to a different environment (network

  • Boolean Instantiation ( BooleanInstantiation ) provided by PMD Basic Rules 5.1.2

    Avoid instantiating Boolean objects; you can reference Boolean.TRUE, Boolean.FALSE, or call Boolean.valueOf() instead.

    Boolean instantiation adds unnecessary complexity and clutters the code.

  • Broken NullCheck ( BrokenNullCheck ) provided by PMD Basic Rules 5.1.2

    The null check is broken since it will throw a NullPointerException itself. It is likely that you used || instead of && or vice versa.

    This pattern impacts the reliability, since an exception may be thrown.

  • Dont Use Float Type For Loop Indices ( DontUseFloatTypeForLoopIndices ) provided by PMD Basic Rules 5.1.2

    Don't use floating point for loop indices: the termination test may misbehave due to floating point granularity. If you must use floating point, use double unless you're certain that float provides enough precision and you have a compelling performance need (space or time).

    This rule impacts reliability, since the loop may terminate at an unexpected time.

  • Double Checked Locking ( DoubleCheckedLocking ) provided by PMD Basic Rules 5.1.2

    Partially created objects can be returned by the Double Checked Locking pattern when used in Java. An optimizing JRE may assign a reference to the baz variable before it creates the object the reference is intended to point to. For more details refer to: http://www.javaworld.com/javaworld/jw-02-2001/jw-0209-double.html

    The double check pattern impacts reliability, since the code may produce a crash or unpredictable behaviour when the half-defined class is used.

  • Jumbled Incrementer ( JumbledIncrementer ) provided by PMD Basic Rules 5.1.2

    Avoid jumbled loop incrementers - it is usually a mistake, and is confusing even if intentional.

    It impacts changeability, since modifying the loop will probably have some side-effects. It also impacts reliability by increasing the complexity of code, thus inducing more opportunities for bugs.

  • Misplaced Null Check ( MisplacedNullCheck ) provided by PMD Basic Rules 5.1.2

    The null check here is misplaced. If the variable is null a NullPointerException will be thrown. Either the check is useless (the variable will never be 'null') or it is incorrect.

    This pattern impacts the reliability, since an exception may be thrown. It also impacts analysability, since the maintainer will take unnecessary time to understand that the null is misplaced.

  • Override Both Equals And Hash code ( OverrideBothEqualsAndHashcode ) provided by PMD Basic Rules 5.1.2

    Override both public boolean Object.equals(Object other), and public int Object.hashCode(), or override neither. Even if you are inheriting a hashCode() from a parent class, consider implementing hashCode and explicitly delegating to your superclass.

    Even if at some time only one of these methods is indeed used, a maintainer will assume that the code is consistent, i.e. the hashCode and equals functions are both overriden to fit the new behaviour.

  • Return From Finally Block ( ReturnFromFinallyBlock ) provided by PMD Basic Rules 5.1.2

    Avoid returning from a finally block, this can discard exceptions.

    It impacts reliability because the caught exception may hide another unseen exception.

  • Unconditional If Statement ( UnconditionalIfStatement ) provided by PMD Basic Rules 5.1.2

    Do not use if statements that are always true or always false.

    A maintainer will have trouble understanding why an unconditional if has been used. It further clutters the code.