Good App, Good Documentation (Ruby on Rails)

Good App, Good Documentation (Ruby on Rails)

Now we'll share the tips about how to create a good App, because there are many apps which has good functionality but lack of documentation. And if we work on project, documentation will increase our project value, I mean our app price. Okay here the tips for good app.

 

 

1. Well Debugged

 

Of course every application have to well debugged, should not contain any bugs when it's goes to live. And to make it well debugged you can use RSpec to test your app and you can found it on our previous post : Rspec in Rails.

 

 

2. Well Commented

 

Yeah this part is the most forgotten part more often for little app. But actually with well commented app that'll help you a lot, especially when you have to develop the app in future. You don't need to trace the whole code to know one issue, just read the information from the comment. In Rails you can put your comment before your action, see the example below.

 

 

[code language="ruby"] class BooksController < ApplicationController # Show all +books+ # # 1.even? # => false # # GET /books # GET /books.json # ==== Examples # # Book.all def index @books = Book.all … end # Create a new book from parameter params[:book] and return in json format # POST /books def create @book = Book.new(params[:book]) … end end [/code]

 

You can see guides.rubyonrails.org/api_documentation_guidelines.html for full documentation about how to write your comment.

 

 

3. Well Documented

 

Well, we are in rails so it'll be easy to generate your documentation if you follow the instruction above, just use rake command to generate your app documentation.

 

 

[code language="ruby"] rake doc:app [/code]

 

This rake command will generate your documentation in folder /doc/app/, open your index.html documentation aaaand viola! You already have your documentation, tidy and easy right? See the screenshot below :

Ruby on Rails Documentation

 

But how if you want to generate your ERD diagram or class diagram? Fortunately you are in rails there are gem to generate your ERD and class diagram.

 

 

4. Rails-ERD

 

Rails-ERD will generate your ERD from database in an instance, you just need follow the instruction written in the documentation, see https://github.com/voormedia/rails-erd. Rails-ERD generates diagrams using Graphviz so don't forget to install it before. In Ubuntu you can use this command.

 

 

[code language="ruby"] > sudo apt-get install graphviz [/code]

 

To install Rails-ERD just add it to your Gemfile and bundle it.

 

 

[code language="ruby"] group :development do gem “rails-erd” end > bundle install [/code]

 

And you will be able to generate erd from rake command.

 

 

[code language="ruby"] > rake erd [/code]

 

That'll generate erd.pdf to view your diagram. You can customize the output, just see rails-erd.rubyforge.org/customise.html.

 

 

5. Railroady

 

Railroady will generate your model and controller UML class diagram. Same with rails-erd this gem need graphviz installed, so if you already have graphviz installed you no need to worry neither you need to check Rails-ERD part to see how to install graphiz. To use this gem just add it to you Gemfile and bundle it.

 

 

[code language="ruby"] group :development do gem 'railroady' end > bundle install [/code]

 

After that do this rake command to generate your model and class UML class diagram.

 

 

[code language="ruby"] rake diagram:all [/code]

 

This should generate four doc/*.svg files. You can see full documentation at github.com/preston/railroady.

Hope this article help you a lot. Happy code! (^_^)

 

 

Written by : Aditia Mahdar – Web Developer at 41studio