Add note explaining why by default we no longer remove unused prototype properties in externs.
@@ -25,6 +25,14 @@ import java.util.logging.Logger;
/**
* Removes unused properties from prototypes.
*
+ * NOTE: When canModifyExterns is true, this pass removes unused prototype properties
+ * in externs. This helped code size in the past, before type-based optimizations existed
+ * (and can help now for things that are not disambiguated), but is unsafe.
+ * For example, it can remove a polyfilled method that is not used in the source, but is
+ * used by the external code, so the call is not visible to the compiler.
+ * Therefore, the default for canModifyExterns is false, even though that increases code size
+ * for some projects.
+ *
* @author nicksantos@google.com (Nick Santos)
*/
class RemoveUnusedPrototypeProperties implements CompilerPass {
