I just started to document a rails application. I know this is actually done by rdoc, so I followed some rdoc guides regarding syntax and so on, but I got stuck when I tried to describe attributes of models, validations and the relationship between models, mostly because these things are part of ActiveRecord. So I wonder if there is some guide or a good practice regarding how to document a rails application or if there is something I'm missing?
I know that I could put all of this in the class description, but I wonder if there is a way more closely tied to the declaration itself (has_many, validates_presence_of, etc.) and what about the attributes?
I personally prefer YARD - http://yardoc.org , as it does a better job in documenting IMHO.
I don't know if there's a specific handler for Rails available, but it's quite easy to write one - http://yardoc.org/guides/extending-yard/writing-handlers.html
A good example might be the attribute handler - part of the yard gem:
lib/yard/handlers/ruby/attribute_handler.rb
Remember your tests are part of the documentation (for developers), particularly if you are using Cucumber where scenarios are easy to read. If you keep your methods very short and there is a test method with a descriptive name e.g. "should set the users name" I find I typically don't need comments on the method.
Validations or other parts of Rails I would not document. Part of being a Rails developer is understanding how these work, I think it is a fair assumption that another maintainer of your code reading it down the road will know validations, or other things built in to Rails. By that same logic, if you can use features of the framework or happy paths (not deviate much) with [documented] third party code, a lot of the documentation will be written for you.
Related
Like most rails folks my restful controllers stick to a very consistent pattern, and any changes are rarely more than an extra line or two.
I like to test (using RSpec) fairly thoroughly, and that includes assigns, responds, redirects etc in controller tests.
The thing is, 75% of my controller specs follow the exact same pattern, and an obvious step seems to be to refactor them into a method/set of methods that I can call from each spec....either with a single (for example) 'restful_controller_specs' call, or individual 'restful_index_specs', 'restful_show_specs' etc for actions if the resource isn't completely standard.
And yet, when looking at other people's projects, from what I can see nobody else really seems to do that.
So in short, am I missing a good reason as to why not to agressively refactor restful controller specs?
I think most rails developers have learned programming by learning rails, which is not the ideal way to learn how to program, so things like refactoring are not a concept they have learned or encountered. Many people don't realise that files like config/routes.rb and db/migrate/* are just ruby code, and you can add loops and arrays and classes and subclasses into them as you need, just like any ruby program.
To all the rails coders out there: learn ruby! learn it well! It's a real programming language! Rails is made entirely of ruby.
I've been going through Ruby (and Ruby on Rails) tutorials online such as RubyMonk, Codeschool courses, the Railstutorial, and Learn Ruby the Hard Way.
These are all excellent resources, but I feel like I need to see some Ruby code that is actually being used in production in order to advance to the next level. I would assume that a repo like Rails would be considered advanced level - so I'm looking for something a little in-between.
Are there some GitHub public repos that are using a more intermediate difficulty level of Ruby coding that I can learn from?
If you can recommend some that would be an appropriate follow-up based on the contents of the tutorials I listed earlier, that would be great.
I've looked some myself, but I'm asking for recommendations because I want to make sure I'm studying something that is "the right way" to do Ruby and not learning bad habits.
Here's two I've created:
http://github.com/rails3book/ticketee - A light-weight project management system from the http://manning.com/katz'>Rails 3 in Action book.
http://github.com/radar/forem - A forum engine for Rails 3 applications.
Both should have pretty good examples of intermediate code, along with tests.
I published a solution to a ThoughtWorks interview problem that I used as the example for a talk. I'm not sure it's "intermediate", but quite a few things in there might fall outside the range of "beginner", so I think it might be up your alley. There's also a rather robust test suite using MiniTest::Spec and mocha.
For example, I use this approach to cause classes which include a module to register themselves with their base class:
module TaxWorks
module TaxStrategy
def self.included(base)
add_strategy base
end
def self.strategies
#strategies ||= []
end
private
def self.add_strategy(s)
strategies << s
end
end
end
In this example, now you can do TaxStrategy.strategies to enumerate the list of possible strategies, after loading any you care about.
Hope that helps!
If you're into Rails you should have a look at these open-source Rails apps:
https://github.com/rubygems/rubygems.org - Source code for rubygems.org, the Rubygems server/website
https://github.com/ryanb/railscasts - Source code for railscasts.com
Both of these apps are exceptionally well organized, clean and thought out. In the case of rubygems.org it's had tons of contributions from different rubyists and is a great working example of Rails in action.
I think Sinatra is a good start. Take a look at Sinatra's source code and build a small MVC application with some helpers. You will not only learn some ruby but also get a good understanding for how Rails work without the magic. It is made "the right way" and you will not learn any bad habits.
I am trying to learn ROR these days and have basic knowledge of ruby, but often working with rails, I get to the point where it seems as if I don't know a bit about ruby.
Just to explain the point, in rails we use has_many keyword. I did not learn any such thing when I was going through ruby tutorials but just came to know that it has something to do with meta-programming in ruby (I have no idea what is meta programming).
So I would like to know if there is any book/tutorial which explain all the points/syntax/concepts of ruby, which a newbie would see while programming in rails.
Thanks to "Jonas Elfström", in simple words, what I am looking for is to know "how Rails uses Ruby"
Thanks.
has_many isn't a keyword, it's simply a class method in the ActiveRecord::Associations module.
It's documented here and you can even view the source if you scroll down a bit.
Associations are a set of macro-like class methods for tying objects
together through foreign keys. They express relationships like
“Project has one Project Manager” or “Project belongs to a Portfolio”.
Each macro adds a number of methods to the class which are specialized
according to the collection or association symbol and the options
hash. It works much the same way as Ruby’s own attr* methods.
If you already know Ruby the Rails Guides could get you going but it might be easier to learn from one of the books listed at the documentation page or by watching a couple of screencasts.
For books about Ruby I've never seen such praise as what Eloquent Ruby gets.
There's a tutorial called Learn Ruby the Hard Way
(written by Rob Sobers of Fog Creek Software)
I tried lately this: http://pine.fm/LearnToProgram/ which helped me a lot because there are one or two concepts that had slipped. I started long ago with an arcane version of this.
I have been using ActiveResource in my Ruby on Rails applications for some time, and I am starting to really feel that it needs a final polish to make it go from "pretty nice" to "beautiful".
I would like to be able to use an ActiveResource as if it were an ActiveRecord. If I could use has\_many, belongs\_to and other niceties with ActiveResources, it would make my life easier.
So I looked around for a plugin to do just that, but haven't had any luck finding one. Has anyone written one? Does anyone know of an ongoing project?
Raison d'être
Let's say I have an application which manages Users, and another application which manages UserRequests. I would like to avoid any circular dependency between my applications, therefore I have decided that the Users application will be completely unaware of the notion of UserRequests. But of course, a UserRequest should belong to a User, and a User should have many UserRequests.
So, in the Users application, all I have is a User ActiveRecord, with all the necessary controller stuff to make it usable through ActiveResource.
The complicated stuff is in the UserRequests application. I have a UserRequest ActiveRecord, and a User ActiveResource. I would love to code the fact that a UserRequest belongs_to a User ActiveResource, and a User ActiveResource has_many UserRequests.
In another scenario where it could be the other way around (the ActiveRecord has_many ActiveResources, and the ActiveResource belongs_to the ActiveRecord).
Ryan Daigle proposed to do something similar with his Roxy gem. From his teaser section:
I hope to have an extension library up
soon that utilizes Roxy to provide
ActiveRecord-like association
definitions in ActiveResource.
The example he gives shows how it wouldn't be too difficult to implement with Roxy.
I just ran across the Hyperactive Resource plugin. I am looking at it right now... looks good.
The funny thing is that I had decided to write my own plugin, and I was looking for a good name for it. I wanted to find a name which would give the feeling that it was "ActiveResource++", an enhanced version of ActiveResource. I hesitated between "SexyResource" and "HyperactiveResource", and I decided that the former was not politically correct enough. So I started to write my HyperactiveResource plugin... until I wondered if someone else had already thought of that name. And it turns out someone did. And the plugin was there. Cool! But it's kind of scary how we developers think alike, isn't it? ;-)
I'm currently working with Groovy and Grails. While Groovy is pretty straight-forward since it's basically Java, I can't say I grok Grails. I read that Groovy is to Grails as Ruby is to Ruby on Rails, but what does that mean?
To address your confusion with the metaphor (though it has been answered in other words under your question):
Groovy is to Grails as Ruby is to Ruby on Rails, but what does that mean?
Grails was a web framework built on/with the Groovy programming language to do the same thing for Groovy that Rails (a web framework for Ruby) does for Ruby.
What does it mean to be "on rails"?
The answer to this comes down to the essence of these web frameworks.
These web frameworks (Grails & Rails) are built on the premise of "convention over configuration", which means that using common conventions to develop web applications can lead to higher productivity and more maintainable applications (this is a gross generalization). And by defining a convention and sticking to that you will find that your applications are easy to generate and quick to get up and running.
This is what it means to me to be "on rails", just like a train. When a new train route is developed there is no worry about reinventing the way the train will get from one place to another, it's been solved by a single convention for decades: rails. Just as the tracks on a train route constrain its path from two locations, convention-based web frameworks use conventions to the flexibility of application developers so that they can concentrate on what the essential business problem of their application.
One key benefit of a convention for a web framework is that the web framework can now make assumptions on how certain layers of the application hook together. In Rails, one can usually assume that if one's database table has a plural name, the ActiveRecord class mapped to that table will have the corresponding singular name. Consequently, Rails code generators can consume the data-mapping information to generate data access code such as dynamic finders, migrations, lazy-loaded association traversals, etc. This data access code in a configuration-based framework is laborious to code by hand.
Several people have mentioned the technicalities of what makes Rails/Grails what they are. Several people have also mentioned "convention over configuration" as being the "rails" in Rails/Grails. This is getting closer to the truth. But this is just one characteristic of the broader philisophy of Rails, which is the concept of opinionated software.
Opinionated software can't be described in only technical terms; it's a philosophy; an ethos; an attitude. Like it or hate it, that is what's at the heart of Rails.
Here's an exceprt from a 2005 interview with David Heinemeier Hansson, creator of Rails:
Rails is opinionated software. It eschews placing the old ideals of software in a primary position. One of those ideals is flexibility—the notion that we should try to accommodate as many approaches as possible, that we shouldn't pass judgement on one form of development over another. Well, Rails does, and I believe that's why it works.
With Rails, you trade flexibility at the infrastructure level to gain flexibility at the application level. If you are happy to work along the golden path that I've embedded in Rails, you gain an immense reward in terms of productivity that allows you to do more, sooner, and better at the application level.
There is also a later interview that further explores the subject.
So being 'on rails' is a metaphor for being 'opinionated', which is why it is named as it is. That and the fact that "Ruby on Rails" is alliteratve, which any journalist or writer will tell you, is a sure-fire way of hooking people's attention.
I think a framework that strives to be "rails-like" refers to several things:
model-level: an AR-patterned ORM (rather than datamapper), migrations or some automated schema and model-layer management, handling foreign keys in the application (not in database schema, and also not using stored procedures or pure DBMS logic)
TDD encouraged: automatically generated skeletons for unit-tests,
naming conventions connecting database table names and model names, controller and view actions and HTML templates
streamlined route recognition and route generation scheme
emphasis on REST architecture
integration with ajax libs: RJS, prototype and scriptaculous
Rails is a framework for developing web applications with a database back-end. I think the name originally was a play on words. A train can take you somewhere really fast, but only where the rails go.
Being on rails means you can't control where you are going. It means, you can only go where the rails have been laid. Any attempt to go where the people who laid the rails didn't anticipate you to go will lead to frustration.
It's an automotive expression. When a car handles exceptionally well, it's said to "corner like driving on rails" (i.e. it gives you excellent control).
I don't know if that's where the rails people got that name, but that's how I interpreted it.
Really short and simple answer: Convention over Configuration.
As said above, Rails and Grails provide conventions for web application development -- naming your pieces a certain way and putting them in the right places get your application working by default with no extra configuration. When you want to deviate from the convention, you can configure your way there.
I disagree with the other comments of "on rails is a philosophy about convention over configuration" and so on.
While rails does adhere to those philosophies, "Ruby on Rails" is the name of a web framework. Nothing more, nothing less. It's not referring to any specific "on-railsness" about it, it's just a brand name in the same way that McDonald's is a brand name.
If someone else writes another framework and calls it "Python on Rails" then there'll be another brand name. If not, "XYZ on rails" just means people are being confused.
Ruby and Groovy are languages.
Ruby on Rails is a ground-breaking webapp framework. See excellent answers on opinionated software above.
As a matter of history, a working title for a Groovy webapp framework was Groovy on Rails. However the RoR community objected. The team chose Grails instead.
It's a metaphor, and I'm almost said that needs explaining. Anyway, it's an extremely good metaphor for what Ruby on Rails does. It makes it extremely easy to do (go to) the common stuff, i. e. testing, validation, deployment, MVC.