complexity-report

Software complexity analysis for JavaScript projects. Command-line front-end for [escomplex]. Less attractive elder brother of [JSComplexity.org][jscomplexity].

• Software complexity analysis
• How it works
• Complexity metrics
• What not to do with the results
• What to do with the results
• Installation
• Usage
  • Command-line options
  • Output formats
• License

Software complexity analysis

Complexity is the quality of consisting of many interrelated parts. When software consists of many interrelated parts, it becomes more difficult to reason about. Software that is difficult to reason about is a more fertile breeding ground for bugs than software that is simple.

Every problem space contains some level of inherent complexity, which is shared by all possible solutions. However, as programmers, we can reduce the complexity of our chosen solutions by limiting the interrelatedness of their constituent components. This is commonly referred to as favouring cohesion over coupling, and forms the bedrock on which axioms such as the single responsibility principle are built.

In codebases that are large and/or unfamiliar, it can be difficult to know whether regions of complexity exist and where they might be. By defining metrics of complexity, the search for offending components can be automated and brought into the existing build process alongside other forms of static analysis and unit tests.

How it works

complexity-report is just a [node.js][node]-based command-line wrapper around [escomplex], which is the library that performs the actual analysis work. Code is passed to escomplex in the form of syntax trees that have been generated with [esprima], the popular JavaScript parser.

[Here is an example report][eg].

Complexity metrics

The readme for escomplex contains a [brief overview of the metrics][metrics] it produces.

What not to do with the results

The numbers returned by this tool should not be interpreted as definitive indicators of whether a piece of software is "too complex", whatever that might mean.

Software development is a varied field and every project is subject to a unique set of environmental factors. Attempts to set generic hard limits for these complexity metrics must essentially be arbitrary and fail to consider the specific requirements of a given project. Further, complexity itself is such an amorphous, multi-dimensional continuum, that attempting to pigeon-hole chunks of code at discrete points along a single axis is an intrinsically crude approach.

What to do with the results

It is better to use this tool as a fuzzy, high-level mechanism, which can identify regions of interest or concern and from which your own programming- and domain-expertise can take over for a more comprehensive analysis.

Although the metrics themselves are not perfect, they can help to identify areas of code that warrant closer inspection. They can also be tracked over time, as an indicator of the direction that overall code quality may be moving in.

The tool can be configured to fail when complexity metrics pass a specified threshold, to aid its usefulness in automated environments / CI. There are also options for controlling how metrics are calculated and the format of the report output.

Installation

You must have [node.js installed][nodeinstall].

Then, for a project-based install:

npm install complexity-report

Or globally for all projects:

sudo npm install -g complexity-report

Usage

cr [options]