Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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