factorylabs-metric_fu 0.8.0.4

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