explains why AS::OrderedHash does not leverage inheritance

1 files changed, 11 insertions, 0 deletions

diff --git a/activesupport/lib/active_support/ordered_hash.rb b/activesupport/lib/active_support/ordered_hash.rb
index 02980d7473..91de722748 100644
--- a/activesupport/lib/active_support/ordered_hash.rb
+++ b/activesupport/lib/active_support/ordered_hash.rb
@@ -23,6 +23,17 @@ module ActiveSupport
 
     # Hash is ordered in Ruby 1.9!
     if RUBY_VERSION < '1.9'
+
+      # In MRI the Hash class is core and written in C. In particular, methods are
+      # programmed with explicit C function calls and polymorphism is not honored.
+      #
+      # For example, []= is crucial in this implementation to maintain the @keys
+      # array but hash.c invokes rb_hash_aset() originally. This prevents method
+      # reuse through inheritance and forces us to reimplement stuff.
+      #
+      # For instance, we cannot use the inherited #merge! because albeit the algorithm
+      # itself would work, our []= is not being called at all by the C code.
+
       def initialize(*args, &block)
         super
         @keys = []