diff --git a/sdk/lib/core/map.dart b/sdk/lib/core/map.dart
index ac4581f7c00..1c29a90f539 100644
--- a/sdk/lib/core/map.dart
+++ b/sdk/lib/core/map.dart
@@ -237,6 +237,9 @@ abstract class Map<K, V> {
    *
    * The order of iteration is defined by the individual `Map` implementation,
    * but must be consistent between changes to the map.
+   *
+   * Modifying the map while iterating the keys
+   * may break the iteration.
    */
   Iterable<K> get keys;
 
@@ -250,6 +253,9 @@ abstract class Map<K, V> {
    * The returned iterable has an efficient `length` method based on the
    * [length] of the map. Its [Iterable.contains] method is based on
    * `==` comparison.
+   *
+   * Modifying the map while iterating the
+   * values may break the iteration.
    */
   Iterable<V> get values;