diff --git a/esphome/core/entity_base.h b/esphome/core/entity_base.h
index 76457ac275..01a1ef7111 100644
--- a/esphome/core/entity_base.h
+++ b/esphome/core/entity_base.h
@@ -88,10 +88,11 @@ class EntityBase {
   // Get whether this Entity should be hidden outside ESPHome
   bool is_internal() const { return this->flags_.internal; }
 
-  // Set whether this Entity should be hidden outside ESPHome. Kept for existing projects that
-  // decide the flag at boot; new designs should use the 'internal:' YAML key. Must be called before
-  // MQTT and the API read the flag: from on_boot at the default priority, or a setup() that runs
-  // above setup_priority::AFTER_WIFI. Calls after setup finishes are ignored and log an error.
+  // Set whether this Entity should be hidden outside ESPHome. Prefer the 'internal:' YAML key
+  // whenever possible: it is guaranteed and has none of the limitations below. Use this only when
+  // the decision can only be made at boot. Must be called before MQTT and the API read the flag:
+  // from on_boot at the default priority, or a setup() that runs above setup_priority::AFTER_WIFI.
+  // Calls after setup finishes are ignored and log an error.
   //
   // Known limitations, all by design and not going to be fixed:
   // - No consumer is notified of a change, so the flag can only be decided once per boot.