This page explains the metrics used by code-inspector and how they are used.

Violations

A code violation is a potential issue in your code. Violations are associated with a category:

  • Best Practice: the code is not following the language best practice (e.g. common function to use, avoid printing the stack trace, do not reassign parameters, etc).
  • Code Style: potential syntax error or language-specific coding style (e.g. correct casing, varible names, etc.), not critical but something that can facilitate maintenance.
  • Documentation: any documentation issues (e.g. function is not documented or parameters documentaition are missing). Low impact on your technical debt (but something to keep in mind for maintenance purposes). Low impact on technical debt.
  • Design: potential design issues in classes or functions (e.g. number of parameters, functions are too long, etc). High impact on technical debt.
  • Deployment: any issue regarding deployment (e.g. deployment script in AWS, etc.). Medium to high impact on technical debt.
  • Error Prone: any statement that can be confusing and impact software maintenance (e.g. comparison issue, statements without any effect). Medium impact on technical debt.
  • Performance: code that negatively impacts your performance (e.g. inefficient code). High impact on technical debt.
  • Security: code that might introduce a buffer overflow or any other security issues. High impact on technical debt.
  • Safety: code that might crash. High impact on technical debt.

Violations are also classified according to a severity between 1 (most critical) to 4 (less critical).

Violations are considered to be potential issues or bugs. The engine makes the assumpations these are potential bugs.

An industry study reported that on average, there are about 15 to 50 errors per 1000 lines of delivered code.

Why it matters?

Violations are potential bugs. They should be fixed to ensure the software works as specified.

What are the thresholds?

Thresholds are based on violations density defined as: number of violations / slocs

  • Between 0 and 0.005: good
  • Between 0.005 and 0.020: warning
  • More than 0.020: error

How to fix violations?

Look at the code related to the violation and if possible, follow advice of the violation to fix it. Once the fix is done, commit the code, analysis will update and violation will disappear.

Duplicates

Code duplicates are often copy/paste that could be avoided by re-factoring the source code and create functions. Very often, developers do not create function to factor the code and instead, copy/paste complete blocks of code. While this is convennient, this incurs technical debt:

  1. if any issue is found in the original block of code, the fix should be applied to all duplicates. As there is no real way to track duplicates, this is very likely that the fix will not be applied consistently across the codebase.
  2. if there original code block needs to be updated to add a new functionality, the new fix should be added to all duplicates. This will then takes time to track down all duplicates and apply the fix.

Why it matters?

Duplicated code increases maintenance efforts and increase the impact of a bug.

What are the thresholds?

Thresholds are based on duplicated lines density defined as: number of duplicated lines of code / slocs

  • Between 0 and 5: good
  • Between 5 and 10: warning
  • More than 10: error

How to fix duplicates?

Analyze the duplicated code and create function that will execute the duplicated code. You will then create more maintainable code that will reduce maintenance efforts.

Cyclomatic Complexity

Cyclomatic Complexity surfaces the complexity of a function. It was invented by McCabe in 1976 and it still considered today as one of the best metric to find complex functions. While there are different opinions about what score or threshold characterize a function as complex, these are the thresholds used by code-inspector engine:

  • 15 < complexity < 25: warning
  • complexity < 25: critical

Why it matters?

Functions that are too complex are hard to understand, maintain and test. They might contain more bugs that non-complex functions.

What are the thresholds?

There are several thresholds we use. The first one is to consider if a function is complex or not. We consider the following threshold to gauge a function complexity:

  • between 0 and 15: no major problem
  • between 15 and 25: higher than usual but might be justified
  • more than 25: need refactor.

In the technical debt view, we show if the project has too many complex functions. The percentage of complex functions is defined as: number of functions with cyclomatic complexity > 15 / number of functions.

There are the thresholds:

  • Between 0 and 5: good
  • Between 5 and 20: warning
  • More than 20: error

How to fix cyclomatic complexity issues?

  1. Avoid doing the same computation over and over. Use variable to store temporary and intermediate results.
  2. Re-factor your code using function. As with duplicates, try to separate a function into sub-functions.

Functions Length

Code should be easily readable so that engineers can understand the code before making any modification. A good rule of thumb is to ensure that a function code can be shown on a screen so that the developer does not have to scroll up and down to read the code.

Why it matters?

Developers should be able to read and understand the code quickly. Long units of code defeat that purpose.

What are the thresholds?

As for the complexity, we need to define what a long function is. We define a long function by the number of total lines (not only lines of code, we also include comments).

  • between 0 and 40 lines: good
  • between 40 and 80 lines: warning
  • more than 80 lines: need refactor.

In the technical debt view, we show if the project has too long functions. The percentage of complex functions is defined as: number of functions with length > 40 / number of functions.

There are the thresholds:

  • Between 0 and 5: good
  • Between 5 and 20: warning
  • More than 20: error

How to fix that?

Re-factor the code into smaller unit of code (functions).