Improved explanation

1 files changed, 16 insertions, 10 deletions

diff --git a/guides/source/engines.md b/guides/source/engines.md
index ccbda7c712..e670962fe6 100644
--- a/guides/source/engines.md
+++ b/guides/source/engines.md
@@ -239,17 +239,19 @@ NOTE: The `ApplicationController` class inside an engine is named just like a
 Rails application in order to make it easier for you to convert your
 applications into engines.
 
-WARNING: Due to the way Rails autoloads controllers, it could happen that the main
-application's `ApplicationController` were loaded before the engine's `ApplicationController`.
-In such case, the Ruby interpreter would not load the latter class and your engine's
-controllers would miss methods defined in it (because they would inherit from main 
-`ApplicationController`). For this reason the code in engine's controllers must explicitly
-tell Ruby they depend on the right application controller. This can be achieved with
-a single line at the top of the controllers files. For example:
+NOTE: Because of the way that Ruby does constant lookup you may run into a situation
+where your engine controller is inheriting from the main application controller and
+not your engine's application controller. Ruby will look in the ancestor chain for
+constants and every class has `Object` as an ancestor, meaning that if the global
+`ApplicationController` is loaded Ruby will return that and not call `const_missing`
+and trigger the Rails autoloading mechanism. The best way to prevent this from
+happening is to use `require_dependency` to ensure that the engine's application
+controller is loaded. For example:
+
+``` ruby
+# app/controllers/blorgh/articles_controller.rb:
+require_dependency "blorgh/application_controller"
 
-```ruby
-# articles_controller.rb:
-require_dependency "blorgh/application_controller"  # Explicit dependency required!
 module Blorgh
   class ArticlesController < ApplicationController
     ...
@@ -257,6 +259,10 @@ module Blorgh
 end
 ```
 
+WARNING: Don't use `require` because it will break the automatic reloading of classes
+in the development environment - using `require_dependency` ensures that classes are
+loaded and unloaded in the correct manner.
+
 Lastly, the `app/views` directory contains a `layouts` folder, which contains a
 file at `blorgh/application.html.erb`. This file allows you to specify a layout
 for the engine. If this engine is to be used as a stand-alone engine, then you