InfoQ

News

Google SoC Series: dcov - Ruby documentation coverage analyzer

Posted by Werner Schuster on Jun 21, 2007 07:00 AM

Community
Ruby
Topics
Code Analysis,
Programming
Tags
Static Analysis,
Google Summer of Code,
Coding Standards,
Code Coverage,
Documentation,
Reporting
Static analysis tools are very useful to keep an eye on code quality, particularly if they're integrated in an automatic build process.  rcov, for example, determines test coverage for Ruby code. A new Google SoC sponsored project called dcov now allows to determine the documentation coverage of Ruby code.

The developer of the project, Jeremy McAnally, explains:
Dcov analyzes the documentation in your project and provides you with a coverage rating (similar to rcov) and (eventually) coverage quality ratings.
[Analysis is] done per functional unit: class, method, and module.
Coverage Quality analysis will make dcov even more interesting:
Right now it's just "Is there a comment?" When the quality analysis comes into play, then things will get more interesting.
Just checking if a functional unit has a comment is useful, but could lead to developers adding useless comments just to get good ratings from dcov. Determining whether a comment is useful or not is a difficult task, so Jeremy made this part of dcov pluggable: 
I actually just refactored the code today to make analyzers separate, hot pluggable classes, so the user can add/remove at will. I'm hoping we'll get some seriously smart linguistic programming guys and gals on the project to help us gauge quality.
The output of dcov will be based on existing Ruby tools too:
I'm in the process of adding Ruby Reports (Ruport) support to the code base, which means we'll output reports in a wide variety of formats as they become available from the Ruport team.
Ruport is an extensible reporting system which allows to take data from a number of input source types (CSV, ActiveRecord models, etc.) and generate reports in various formats (PDF, HTML, etc.).

Since dcov analyses Ruby code, it's interesting to see what tools Jeremy used for this:
All code is parsed by the RDoc "parse_files" method and then we take the parsed structure and analyze it. I started to try to find a way to do it manually that was cleaner (or to use something like parse_tree), but I found that RDoc made sense because (a) it's simpler and (b) it's part of the standard Ruby distribution, so everyone should have it.
RDoc provides access to Ruby code via Code Objects, which represent classes, methods, etc. and their comments. 

The project is hosted at RubyForge, Jeremy will be maintaining a blog too. Jeremy also has a book "Mr. Neighborly's Humble Little Ruby Book" available here at InfoQ.

No comments

Reply

Exclusive Content

VMware Infrastructure 3 Book Excerpt and Author Interview

VMware Infrastructure 3: Advanced Technical Design Guide and Advanced Operations Guide provides a wealth of practical insights into setting up virtualization in todays corporate environments.

Architectures of extraordinarily large, self-sustaining systems

Can a system that is so large it cannot be comprehended be "designed" in a conventional sense? The foundations of computing are about to change. In this talk, Richard P. Gabriel explores why and how.

Using Ruby Fibers for Async I/O: NeverBlock and Revactor

Ruby 1.9's Fibers and non-blocking I/O are getting more attention - we talked to Mohammad A. Ali of the NeverBlock project and Tony Arcieri of the Revactor project.

Agile and Beyond - The Power of Aspirational Teams

Tim Mackinnon talks about the aspirations behind the Agile principles and practices, the desire to become efficient, to write quality code which does not end up being thrown away.

Concurrency: Past and Present

Brian Goetz discusses the difficulties of creating multithreaded programs correctly, incorrect synchronization, race conditions, deadlock, STM, concurrency, alternatives to threads, Erlang, Scala.

ActionScript 3 for Java Programmers

Often the hardest part of changing technologies is language syntax differences. This new article provides Java developers with a transition guide to Actionscript which forms the foundation of Flex.

Neal Ford On Programming Languages and Platforms

Neal Ford talks about having multiple languages running on one of the two major platforms: Java and .NET. He also presents the advantages offered by Ruby compared to static languages like Java or C#.

Future Directions for Agile

David Anderson talks about the history of Agile, the current status of it and his vision for the future. The role of Agile consists in finding ways to implement its principles.