RubyCritic wraps around static analysis gems such as Reek, Flay and Flog to provide a quality report of your Ruby code.
Each of these gems are internally wrapped as an Analyser, with a collection of AnalysedModules, which give us calculations of key metrics. The most important ones are churn, complexity, cost and rating.
The output of RubyCritic will give you four values to help you judge your code's odorousness:
- Score: A generic number representing overall quality of the analysed code
- Churn: Number of times a file was changed
- Complexity: Amount of pain in your code
- Rating: The grade assigned to a file
RubyCritic's rating system was inspired by Code Climate's, you can read more about how that works here. Note that the global score is fairly different from Code Climate's GPA, although it serves the same purpose.
Is a value that ranges from 0 to 100, where higher values are better (less code smells detected) and is intended to provide a quick insight about the overall code quality.
This is basically an average of the calculated cost of each file. There is a threshold to avoid very bad modules from having excessive impact.
Churn is very simple to calculate - it is the number of times the file was committed.
Complexity is the output of Flog. You can read more about how it works, but here's a quick summary:
It works based on counting your code's ABCs:
A - Assignments. When more objects are assigned, the complexity goes up - foo = 1 + 1.
B - Branches. When code branches, there are multiple paths that it might follow. This also increases it's complexity.
C - Calls. When code calls other code, the complexity increases because they caller and callee are now connected. A call is both a method call or other action like eval or puts.
All code has assignments, branches, and calls. Flog's job is to check that they aren't used excessively or abused.
Both churn and complexity are presented as a chart:
Each file is represented by a dot. The closer they are to the bottom-left corner, the better.
But keep in mind that you cannot reduce churn (well... not unless you re-write your repo's history ), so try to keep the dots as close to the bottom as possible.
Chad made a nice summary if you want to know more about the meaning behind each quadrant.
This is a letter from A
to F
, A
being the best. This serves as a baseline to tell you how smelly a file is.
Generally A
's & B
's are good enough, C
's serve as a warning and D
's & F
's are the ones you should be fixing.
Rating is simply a conversion from the calculated cost to a letter.
The definition of this cost varies from tool to tool, but it's always a non-negative number, with high values indicating worse smells. The complexity of a file also (slightly) affects its final cost.