If you’ve been using Reek to help in refactoring your Rails applications, you might run across warnings of Irresponsible Modules— that is, code with no comments to help explain what it does. A common knock on the Rails community is that we don’t document our code. I hate to admit it, but it’s fair. My own Rails project folders are full of uncommented methods and mysterious model attributes. If I can’t remember specifics about my code, how can I expect someone else to pick it up?
The good news is there are quite a few documentation tools out there. Here are three you can get started with quickly to bring your application’s code documentation up to speed.
The first tool is an oldie, but still works great: The annotate-models gem refers to your database schema and adds field details in the comments of the corresponding model. Install the gem,
cd into your Rails project directory, and type
annotate to add this documentation to your models. You can also document your tests, specs, and factories—see the GitHub repository for more details.
Now that you’ve got your models annotated (and have added some descriptive comments to your controllers, right?) you can turn it into browser-friendly HTML using the following built-in Rake task:
Be sure to also edit the file
doc/READ_ME_FOR_APP; that’s what the Rake task uses for your documentation’s starter file. Open
doc/app/index.html in your browser to access your app’s documentation.
Finally, how about some visual documentation of how your models relate to one another? Check out Rails ERD a new gem that creates nice PDF entity-relationship diagrams for your apps. It’s easy to install, customizable, and very well documented. Take a look at the gallery of ERD examples from popular open source Rails projects to get a feel for how it works. The rendered PDF saves to your application root by default—I check this into my source control for other developers (not to mention for my own reference).
This list is by no means exhaustive. Refer to Ruby Toolbox’s list of Ruby documentation tools for more options.
I stand with the Black community against systemic racism, police violence and brutality, intolerance, and hate in the United States and worldwide. We must all demand better from our leaders, and ourselves. Stop tolerating intolerance.
While you're here, please consider making a donation to Black Girls CODE, who do great, important work to provide opportunity to underprivileged girls interested in tech, or any organization working toward equity and safety for all, not just the privileged. Thank you.
If you liked my series on practical advice for adding reliable tests to your Rails apps, check out the expanded ebook version. Lots of additional, exclusive content and a complete sample Rails application.
Ruby on Rails news and tips, and other ideas and surprises from Aaron at Everyday Rails. Delivered to your inbox on no particular set schedule.