Replace the giant comment in routes.rb with a link to the guides

This comment not only serves no purpose, but in my experience is
actively detrimental to new developers getting started with Rails.
Expereinced developers just end up deleting this comment, and are
annoyed that they had to take this step. I also spend a lot of time
mentoring brand new developers, and a consistent theme I've seen is that
this comment just ends up intimidating them, and making them think it's
dangerous to edit this file.

One of my students just said this (due to the number of comments which
even new developers don't actually read, they just see it as a sign that
this thing is "dangerous").

> I don't edit any file that Rails generates for me, until my instructor
> says that it's OK to do so.

Realistically, this comment adds 0 value. We have very good
documentation, which we can just link to instead. If someone is truly
new enough to benefit from this info, they presumably just ran `gem
install rails`, and have an internet connection that they can use to
read the routing guide.

The choice of language here was very specific. I chose "the DSL
available" over "what is possible", because a consistent theme I've
noticed among my students is that they aren't aware that this is
actually a Ruby file, and can write any Ruby code here that they want.

This file is not the only offender, but is by far the biggest point of
pain that I've seen, and felt it was a good spot to open this
discussion.
This commit is contained in:
Sean Griffin 2015-07-24 17:22:22 -06:00
parent d937a1175f
commit 12e5cb5db3

@ -1,56 +1,3 @@
Rails.application.routes.draw do
# The priority is based upon order of creation: first created -> highest priority.
# See how all your routes lay out with "rake routes".
# You can have the root of your site routed with "root"
# root 'welcome#index'
# Example of regular route:
# get 'products/:id' => 'catalog#view'
# Example of named route that can be invoked with purchase_url(id: product.id)
# get 'products/:id/purchase' => 'catalog#purchase', as: :purchase
# Example resource route (maps HTTP verbs to controller actions automatically):
# resources :products
# Example resource route with options:
# resources :products do
# member do
# get 'short'
# post 'toggle'
# end
#
# collection do
# get 'sold'
# end
# end
# Example resource route with sub-resources:
# resources :products do
# resources :comments, :sales
# resource :seller
# end
# Example resource route with more complex sub-resources:
# resources :products do
# resources :comments
# resources :sales do
# get 'recent', on: :collection
# end
# end
# Example resource route with concerns:
# concern :toggleable do
# post 'toggle'
# end
# resources :posts, concerns: :toggleable
# resources :photos, concerns: :toggleable
# Example resource route within a namespace:
# namespace :admin do
# # Directs /admin/products/* to Admin::ProductsController
# # (app/controllers/admin/products_controller.rb)
# resources :products
# end
# For details on the DSL available within this file, see http://guides.rubyonrails.org/routing.html
end