forked from prasanna/saikuro
-
Notifications
You must be signed in to change notification settings - Fork 4
/
README
147 lines (109 loc) · 4.97 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
The japgolly fork is a part of an attempt to get metric_fu working in a modern
Ruby environment, specifically compatibility with Ruby 1.9 and Bundler.
===============================================================================
Version 0.2
Saikuro:
Saikuro is a Ruby cyclomatic complexity analyzer. When given Ruby
source code Saikuro will generate a report listing the cyclomatic
complexity of each method found. In addition, Saikuro counts the
number of lines per method and can generate a listing of the number of
tokens on each line of code.
License:
Saikuro uses the BSD license.
Installation:
Option 1: Using setup.rb
* login as root
* run "ruby setup.rb all"
Option 2: The manual way
Saikuro is a single Ruby file that is executable. You can run it where
you unpacked it or you can move it your preferred location such as
"/usr/local/bin" or "~/bin".
Note:
Ruby 1.8.5 has a bug in ri_options that will prevent Saikuro from
running. If you are using 1.8.5 please apply this patch :
http://www.ruby-lang.org/cgi-bin/cvsweb.cgi/ruby/lib/rdoc/ri/ri_options.rb.diff?r1=1.2.2.13;r2=1.2.2.14
Usage:
Saikuro is a command line program.
Running "saikuro -h" will output a usage statement describing all
the various arguments you can pass to it.
"saikuro -c -p tests/samples.rb"
The above command is a simple example that generates a cyclomatic
complexity report on the samples.rb file, using the default filter,
warning and error settings. The report is saved in the current
directory.
A more detailed example is
"saikuro -c -t -i tests -y 0 -w 11 -e 16 -o out/"
This will analyze all Ruby files found in the "tests/" directory.
Saikuro will generate a token count report and a cyclomatic complexity
report in the "out" directory . The "-y 0" command will turn off
filtering and thus show the complexity of all methods. The "-w 11"
will mark all methods with a complexity of 11 or higher with a
warning. Finally, "-e 16" will flag all methods with a complexity of
16 or higher with an error.
About Cyclomatic Complexity:
The following document provides a very good and detailed description
by the author of cyclomatic complexity.
NIST Special Publication 500-235
Structured Testing: A Testing Methodology Using the Cyclomatic
Complexity Metric
By Arthur H. Watson and Thomas J. McCabe
HTML
http://hissa.nist.gov/HHRFdata/Artifacts/ITLdoc/235/title.htm
PDF
http://www.mccabe.com/iq_research_nist.htm
How and what Saikuro counts to calculate the cyclomatic complexity:
Saikuro uses the Simplified Complexity Calculation, which is just
adding up the number of branch points in a method.
Each method starts with a complexity of 1, because there is at least
one path through the code. Then each conditional or looping operator
(if, unless, while, until, for, elsif, when) adds one point to the
complexity. Each "when" in a case statement adds one point. Also each
"rescue" statement adds one.
Saikuro also regards blocks as an addition to a method's complexity
because in many cases a block does add a path that may be traversed.
For example, invoking the "each" method of an array with a block would
only traverse the give block if the array is not empty. Thus if you
want to find the basis set to get 100% coverage of your code then a
block should add one point to the method's complexity. It is not yet
for sure however to what level the accuracy is decreased through this
measurement, as normal Ruby code uses blocks quite heavily and new
paths are not necessarily introduced by every block.
In addition, the short-circuiting "and" operators (&& and "and")
currently do not contribute to a method's complexity, although
McCabe's paper listed above suggests doing so.
#Example for "and" operator handling:
# Starting values for case 1 and 2
x = false
y = 15
r, q = nil
# case 1
puts "W" if ((r = x) && (q = y))
puts r # => false
puts q # => nil
# case 2
puts "W" if ((q = y) && (r = x))
puts r # => false
puts q # => 15
Case 1 illustrates why "and" operators should add to a method's
complexity, because the result of ( r = x ) is false the if statement
stops and returns false without evaluating the ( q = y ) branch. Thus
if a total coverage of source code is desired, one point should be
added to the method's complexity.
So why is it not added?
Mainly, because we have not gotten around to it. We are wondering if
this would increase the noise more than it should.
Tests:
In the test directory is a sample file that has examples of the
various possible cases that we examined and documented the expected
cyclomatic complexity result. If you find mistakes or missing tests
please report them.
Contact:
Saikuro is written by
Zev Blut (zb at ubit dot com)
Acknowledgments:
Thanks to Elbert Corpuz for writing the CSS for the HTML output!
Other metric tools for Ruby:
Ryan Davis has an abc metric program as an example in his ParseTree
product: http://www.zenspider.com/ZSS/Products/ParseTree/
The PMD project has a tool called CPD that can scan Ruby source code
looking for source duplication: http://pmd.sourceforge.net/