diff --git a/lib/legacy/class.js b/lib/legacy/class.js
index 1d0e336573..9201283e09 100644
--- a/lib/legacy/class.js
+++ b/lib/legacy/class.js
@@ -336,6 +336,7 @@ function GenerateClassFromInfo(info, Base) {
  *   to become class methods.
  * @template T
  * @param {function(T):T} mixin Optional mixin to apply to legacy base class
+ *   before extending with Polymer metaprogramming.
  * @return {function(new:HTMLElement)} Generated class
  */
 export const Class = function(info, mixin) {
diff --git a/lib/legacy/legacy-data-mixin.js b/lib/legacy/legacy-data-mixin.js
index a2443c7926..5aee1e0209 100644
--- a/lib/legacy/legacy-data-mixin.js
+++ b/lib/legacy/legacy-data-mixin.js
@@ -140,6 +140,9 @@ export const LegacyDataMixin = dedupingMixin(superClass => {
 
 });
 
+// LegacyDataMixin is applied to base class _before_ metaprogramming, to
+// ensure override of _addPropertyEffect et.al. are used by metaprogramming
+// performed in _finalizeClass
 Polymer.Class = (info, mixin) => Class(info, 
   superClass => mixin ? 
     mixin(LegacyDataMixin(superClass)) :