{"action":"created","issue":{"url":"https://api.github.com/repos/rails/rails/issues/21021","labels_url":"https://api.github.com/repos/rails/rails/issues/21021/labels{/name}","comments_url":"https://api.github.com/repos/rails/rails/issues/21021/comments","events_url":"https://api.github.com/repos/rails/rails/issues/21021/events","html_url":"https://github.com/rails/rails/pull/21021","id":97169139,"number":21021,"title":"Replace the giant comment in routes.rb with a link to the guides","user":{"login":"sgrif","id":1529387,"avatar_url":"https://avatars.githubusercontent.com/u/1529387?v=3","gravatar_id":"","url":"https://api.github.com/users/sgrif","html_url":"https://github.com/sgrif","followers_url":"https://api.github.com/users/sgrif/followers","following_url":"https://api.github.com/users/sgrif/following{/other_user}","gists_url":"https://api.github.com/users/sgrif/gists{/gist_id}","starred_url":"https://api.github.com/users/sgrif/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/sgrif/subscriptions","organizations_url":"https://api.github.com/users/sgrif/orgs","repos_url":"https://api.github.com/users/sgrif/repos","events_url":"https://api.github.com/users/sgrif/events{/privacy}","received_events_url":"https://api.github.com/users/sgrif/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":2,"created_at":"2015-07-24T23:36:12Z","updated_at":"2015-07-25T00:26:41Z","closed_at":null,"pull_request":{"url":"https://api.github.com/repos/rails/rails/pulls/21021","html_url":"https://github.com/rails/rails/pull/21021","diff_url":"https://github.com/rails/rails/pull/21021.diff","patch_url":"https://github.com/rails/rails/pull/21021.patch"},"body":"This comment not only serves no purpose, but in my experience is\r\nactively detrimental to new developers getting started with Rails.\r\nExpereinced developers just end up deleting this comment, and are\r\nannoyed that they had to take this step. I also spend a lot of time\r\nmentoring brand new developers, and a consistent theme I've seen is that\r\nthis comment just ends up intimidating them, and making them think it's\r\ndangerous to edit this file.\r\n\r\nOne of my students just said this (due to the number of comments which\r\neven new developers don't actually read, they just see it as a sign that\r\nthis thing is \"dangerous\").\r\n\r\n> I don't edit any file that Rails generates for me, until my instructor\r\n> says that it's OK to do so.\r\n\r\nRealistically, this comment adds 0 value. We have very good\r\ndocumentation, which we can just link to instead. If someone is truly\r\nnew enough to benefit from this info, they presumably just ran `gem\r\ninstall rails`, and have an internet connection that they can use to\r\nread the routing guide.\r\n\r\nThe choice of language here was very specific. I chose \"the DSL\r\navailable\" over \"what is possible\", because a consistent theme I've\r\nnoticed among my students is that they aren't aware that this is\r\nactually a Ruby file, and can write any Ruby code here that they want.\r\n\r\nThis file is not the only offender, but is by far the biggest point of\r\npain that I've seen, and felt it was a good spot to open this\r\ndiscussion."},"comment":{"url":"https://api.github.com/repos/rails/rails/issues/comments/124776140","html_url":"https://github.com/rails/rails/pull/21021#issuecomment-124776140","issue_url":"https://api.github.com/repos/rails/rails/issues/21021","id":124776140,"user":{"login":"edwardloveall","id":49549,"avatar_url":"https://avatars.githubusercontent.com/u/49549?v=3","gravatar_id":"","url":"https://api.github.com/users/edwardloveall","html_url":"https://github.com/edwardloveall","followers_url":"https://api.github.com/users/edwardloveall/followers","following_url":"https://api.github.com/users/edwardloveall/following{/other_user}","gists_url":"https://api.github.com/users/edwardloveall/gists{/gist_id}","starred_url":"https://api.github.com/users/edwardloveall/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/edwardloveall/subscriptions","organizations_url":"https://api.github.com/users/edwardloveall/orgs","repos_url":"https://api.github.com/users/edwardloveall/repos","events_url":"https://api.github.com/users/edwardloveall/events{/privacy}","received_events_url":"https://api.github.com/users/edwardloveall/received_events","type":"User","site_admin":false},"created_at":"2015-07-25T00:26:41Z","updated_at":"2015-07-25T00:26:41Z","body":"As someone who recently switched over to the \"less comments are better\" camp I like this and pretty much agree with your points. Someone recently said \"Comments are future lies\" referring to upgrading versions of rails where some of these APIs go out of date."}}