Feeds:
Posts
Comments

Archive for July, 2013

complexity-report: a node package for reporting code complexity metrics in JavaScript projects

Posted in JavaScript, Node packages, Tools, tagged , , , on July 10, 2013| Leave a Comment »

complexity-report is a tool for reporting code complexity metrics in JavaScript projects. As a general rule, the more complex the code, the more buggy it is going to be. Therefore, it is a good idea to try to keep your code simple.

complexity-report is a node package which can be installed using the following command:

npm install -g complexity-report

The tool can then be run from the command line. See the complexity-report website for a list of the available options.

The tool currently reports the following metrics for each function:

Line No.
The line number on which the function’s code starts.
Physical SLOC
SLOC stands for “source lines of code”. Physical SLOC is therefore the number of physical lines of code.
Logical SLOC
The number of logical lines of code.
Parameter count
A large number of parameters can indicate that a new object should be created to group them.
Cyclomatic complexity
The number of linearly independent paths through a program’s source code. A high number is bad and generally leads to more bugs. As a rule of thumb, aim to keep the cyclomatic complexity under ten for each function.
Halstead difficulty, volume and effort
The number of bugs (B) increases with difficulty (D), volume (V) and effort (E). Estimates for the number of delivered bugs can be calculated from these metrics as B = E 2/3 / 3000 or B = V / 3000.

In addition, complexity-report also reports an overall figure for:

Maintainability
The maintainability index aims to measure the ease with which the code can be maintained in order to isolate and correct defects, meet new requirements or cope with environmental changes. It is calculated from metrics such as the number of lines of code and Halstead complexity measures.
Aggregate cyclomatic complexity
An attempt at measuring the overall cyclomatic complexity of the code.
Mean parameter count:
The mean number of parameters per function.

Phil Booth gives a good overview of the different types of complexity measured at JSComplexity.org. You also might like to take a look at Wikipedia’s entry on Halstead complexity measures for further details, including how they are calculated.

Advertisement

Read Full Post »

Kalei Styleguide

Posted in CSS, HTML, Tools on July 9, 2013| Leave a Comment »

This post continues on the theme of CSS documentation and the automatic generation of Style Guides. I have finally got around to taking a look at Kalei Styleguide.

Kalei is a tool developed by Thomas Davis, Luke Brooker and Richard Barret. It generates bootstrap-like documentation for your CSS:

Kalei1

 

Kalei has an advantage over StyleDocco in that it does not require a build step. Instead it runs on an HTTP server and documentation is generated on the fly.

The steps I followed to get it working were quite straightforward:

  • If you don’t already have a Git client, you can download and install one from http://git-scm.com
  • The next step is to clone the git repository git://github.com/thomasdavis/kaleistyleguide.git.
  • Now you need to serve Kalei on an HTTP server. I set up a Kalei website in IIS. Help desk geek has some instructions for how to Install and Setup a Website in IIS8 on Windows 8. You may also need to edit the permissions of the folder in which you have placed Kalei in order to access it.
  • Finally, I edited edit js/config.js to point at my own styles.css

I then opened the website in a browser and started playing around with editing my stylesheet.

Taking inspiration from StyleDocco, Kalei also uses markdown syntax for creating the content. However, the lack of a build step makes Kalei a much nicer tool to work with. You can simply edit your CSS files and directly refresh your browser to view the changes. I can see this speeding up my development time massively, and it takes any hassle out of using the tool. It also ensures that the Style Guide truly is a living style guide, and will never get out of sync with your CSS files.

Kalei produces a menu of headings on the left hand side of the web page. This is a helpful touch and enables you to quickly navigate to the stylesheet or section in which you are interested.

Like StyleDocco, the main part of the page contains the actual example elements and HTML required to generate them. It does not, however, show the associated CSS markup. I didn’t find I particularly missed this though, as it makes for a cleaner UI.

My overall initial impression of StyleDocco is very favourable, and I look forward to using it in more earnest.

Read Full Post »