From 723837b3efb7be3e3621d5e3ca3ef0221fbc2764 Mon Sep 17 00:00:00 2001
From: Alice Boxhall <aboxhall@chromium.org>
Date: Thu, 8 Oct 2020 16:06:51 +1100
Subject: [PATCH] Changes from Tess' review

---
 index.bs | 73 +++++++++++++++++++++++++++++++++-----------------------
 1 file changed, 43 insertions(+), 30 deletions(-)

diff --git a/index.bs b/index.bs
index 024cc1e2..ab5a6708 100644
--- a/index.bs
+++ b/index.bs
@@ -855,9 +855,22 @@ doesn't need to handle the possibility of the list changing in the middle.
 
 <div class="example">
 {{Document/getElementsByTagName}} returns a live object which represents a list,
-meaning that authors need to take care when iterating over its items.
+meaning that authors need to take care when iterating over its items:
+
+```js
+let list = document.getElementsByTagName("td");
+
+for (let i = 0; i < list.length; i++) {
+    let td = list[i];
+    let tr = document.createElement("tr");
+    tr.innerHTML = td.outerHTML;
+
+    // This has the side-effect of removing td from the list,
+    // causing the iteration to become unpredictable.
+    td.parentNode.replaceChild(tr, td);
+}
+```
 
-<!-- does anyone know more specifics here? -->
 The choice to have {{ParentNode/querySelectorAll()}} return static objects
 was made after spec authors noticed that {{getElementsByTagName}}
 was causing problems.
@@ -872,11 +885,11 @@ this advice may not apply,
 since these types were designed to behave well
 when they change while being iterated.
 
-If it would be complex to keep the data needed by an object up to date,
+If it would not be possible to compute properties
+at the time they are accessed,
 a static object avoids having to keep the object updated
 until it's garbage collected,
 even if it isn't being used.
-<!-- why wouldn't it be computed lazily though? -->
 
 If a static object represents some state which may change frequently,
 it should be returned from a method,
@@ -886,31 +899,6 @@ See also:
 
 * [[#attributes-like-data]]
 
-<h3 id="optional-parameters">Make function parameters optional if possible</h3>
-
-If a parameter for an API function has a reasonable default value,
-make that parameter optional and specify the default value.
-
-<div class="example">
-{{EventTarget/addEventListener()}} takes an optional boolean `useCapture` argument.
-Thie defaults to `false`, meaning that
-the event should be dispatched to the listener in the bubbling phase by default.
-</div>
-
-Note: Exceptions have been made for legacy interoperability reasons
-(such as {{XMLHttpRequest}}),
-but this should be considered a design mistake rather than recommended practice.
-
-The API must be designed so that if a parameter is left out,
-the default value used is the same as
-converting `undefined` to the type of the parameter.
-For example, if a boolean parameter isn't set,
-it must default to false.
-
-See also:
-
-* [[#prefer-dict-to-bool]]
-
 <h3 id="prefer-dict-to-bool">Prefer dictionary parameters over primitive parameters</h3>
 
 API methods should generally use dictionary parameters
@@ -971,6 +959,31 @@ See also:
 * [[#optional-parameters]]
 * [[#naming-optional-parameters]]
 
+<h3 id="optional-parameters">Make function parameters optional if possible</h3>
+
+If a parameter for an API function has a reasonable default value,
+make that parameter optional and specify the default value.
+
+<div class="example">
+{{EventTarget/addEventListener()}} takes an optional boolean `useCapture` argument.
+Thie defaults to `false`, meaning that
+the event should be dispatched to the listener in the bubbling phase by default.
+</div>
+
+Note: Exceptions have been made for legacy interoperability reasons
+(such as {{XMLHttpRequest}}),
+but this should be considered a design mistake rather than recommended practice.
+
+The API must be designed so that if a parameter is left out,
+the default value used is the same as
+converting `undefined` to the type of the parameter.
+For example, if a boolean parameter isn't set,
+it must default to false.
+
+See also:
+
+* [[#prefer-dict-to-bool]]
+
 <h3 id="naming-optional-parameters">Naming optional parameters</h3>
 
 Name optional parameters to make the default behavior obvious
@@ -1068,7 +1081,7 @@ are non-constructible because they are singletons
 representing access to per-window information.
 In these cases, something like the Web IDL <a>namespace</a> feature
 might have been a better fit,
-but were designed before namespaces,
+but these features were designed before namespaces,
 and go beyond what is currently possible with namespaces.
 
 If your API requires this type of singleton,