12e5cb5db3
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. |
||
|---|---|---|
| .. | ||
| exe | ||
| lib | ||
| test | ||
| .gitignore | ||
| CHANGELOG.md | ||
| MIT-LICENSE | ||
| railties.gemspec | ||
| Rakefile | ||
| RDOC_MAIN.rdoc | ||
| README.rdoc | ||
= Railties -- Gluing the Engine to the Rails Railties is responsible for gluing all frameworks together. Overall, it: * handles the bootstrapping process for a Rails application; * manages the +rails+ command line interface; * and provides the Rails generators core. == Download The latest version of Railties can be installed with RubyGems: * gem install railties Source code can be downloaded as part of the Rails project on GitHub * https://github.com/rails/rails/tree/master/railties == License Railties is released under the MIT license: * http://www.opensource.org/licenses/MIT == Support API documentation is at * http://api.rubyonrails.org Bug reports can be filed for the Ruby on Rails project here: * https://github.com/rails/rails/issues Feature requests should be discussed on the rails-core mailing list here: * https://groups.google.com/forum/?fromgroups#!forum/rubyonrails-core