Ruby Quality Report

Installation

gem install quality_report

Usage

Change to a project directory that contains *.rb files. Then:

ruby-quality-report

After a bit of a wait, it outputs a report in table form:

Screenshot

This is showing, for each author, the percentage of problematic lines of code in the repo. Lower is better.

For improved relevance, it has two filters.

It excludes:

  • authors with fewer than 200 lines of code
  • authors with no commits in the previous 60 days

In Rails Projects

This works great in Rails projects. It examines code recursively starting in the current directory. In my testing, I like the results best when run from /app. This is how I generated the report, above.

How it works

It runs a subset of Rubocop Metrics cops on *.rb files that flag single lines or methods:

Then, using git, it calculates the percentage of warnings per line written, per author. Each failing check is another warning.

Intent

This is a team management tool to:

  • understand the quality of the code your team is producing
  • identify programmers who'd benefit from mentorship and education

Foundational Research

Diving a little deeper, I've seen the phenomenon of "micro-economies" of bug-creation and bug-fixing develop within teams. Some developers appear to be extremely productive. They create a lot of commits. But they also create a lot of bugs. Their productivity is illusory.

This code quality report doesn't track bugs per se. But it does report quality and complexity. Researchers have found a strong correlation between complexity and bug rate [1]. This link is reflected, e.g., in international safety standards that mandate low software complexity to reduce failures [2].

Complex code introduces bugs in a second, more subtle way. This is because code complexity is the killer of understandability. Studies have found that developers devote 64% of their time to understanding code, while only 5% is spent on actually modifying it [3].

  1. De Silva, Dilshan, et al. The Relationship between Code Complexity and Software Quality: An Empirical Study. 2023, https://www.researchgate.net/publication/370761578_The_Relationship_between_Code_Complexity_and_Software_Quality_An_Empirical_Study.
  2. See e.g., ISO 26262-1:2018(En), Road Vehicles — Functional Safety — Part 1: Vocabulary. https://www.iso.org/obp/ui/en/#iso:std:iso:26262:-1:ed-2:v1:en. Accessed 29 Sept. 2024.
  3. Feitelson, Dror G. “From Code Complexity Metrics to Program Comprehension.” Communications of the ACM, vol. 66, no. 5, May 2023, pp. 52–61. DOI.org (Crossref), https://doi.org/10.1145/3546576.

Roadmap

  • [x] Colorize the output to separate high, medium, and low warning percentages.
  • [x] Fix the numerical alignment.
  • [ ] --add-column option.
  • [ ] --skip option.
  • [ ] Add a progress bar.
  • [ ] Speed up the scan.
  • [ ] Refactor from script-style coding to a more standard Ruby project.
  • [ ] Make the filters configurable.
  • [ ] Add a --csv option.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/dogweather/ruby-quality-report.