| 16:27 | <shu> | Michael Ficarra: bakkot i've invited Nicolò€ to some future editor call to brainstorm ideas to make the module machinery editorially easier to understand |
| 16:28 | <bakkot> | great |
| 16:28 | <Michael Ficarra> | awesome |
| 21:05 | <Michael Ficarra> | new editorial convention just dropped:do not use determiners or pronouns to refer to values from other steps (e.g. "that number"); instead uses aliases or repetition |
| 21:19 | <shu> | who said that |
| 21:20 | <shu> | what's wrong with "that number" |
| 21:32 | <Michael Ficarra> | you should assign it to an alias and refer to the alias instead of hand-waving at things from earlier steps |
| 21:33 | <Michael Ficarra> | the context of this was a PR that referred to a Unicode data file in one step and then hand-waved a reference to "that line" from the file in the next step |
| 21:33 | <Michael Ficarra> | also added:assertion steps should not be necessary to understand an algorithm; a reader should interpret it the same if they are removed |
| 21:34 | <Michael Ficarra> | inspired by the same line, since the "prior step" there was actually an assertion step |
| 21:34 | <shu> | sometimes it is clear from context, sometimes it is not |
| 21:34 | <Michael Ficarra> | I can drop the convention for now or leave it in until we can discuss at editor call |
| 21:35 | <Michael Ficarra> | I added it because I thought it would be uncontroversial |
| 21:38 | <Michael Ficarra> | I would also like to add another one:do not include unnecessary demonstrative determiners ( |
| 21:40 | <Michael Ficarra> | @shu here was the specific line btw: https://github.com/tc39/ecma262/pull/3587/files/37ad780a824f42495276961ee32bcc2ce6c3241b#diff-181371b08d71216599b0acccbaabd03c306da6de142ea6275c2135810999805aR38582 |
| 22:55 | <bakkot> | I don't have a problem with "that number"; it's fine when it's clear and when not clear the problem is that it is not clear |
| 22:56 | <bakkot> | I also don't have a problem with the String _v_ unless it's obvious from context that _v_ is a string |
| 22:57 | <bakkot> | I agree with the assert one |
| 23:02 | <Michael Ficarra> | this one I think we should talk about more in editor call |
| 23:04 | <Michael Ficarra> | is a return value of an AO whose return type is declared obvious? is a value retrieved from a call of an AO whose return type is declared obvious? |
| 23:05 | <bakkot> | I mean, sometimes? |
| 23:05 | <bakkot> | we cannot codify "be clear" as a specific set of rules around which words to use when |
| 23:06 | <bakkot> | we are not going to come up with a set of rules that can tell you exactly how to write each step and we shouldn't try |
| 23:06 | <bakkot> | it's prose |
| 23:11 | <jmdyck> | If someone is inclined to use the String _v_, they should consider Assert: _v_ is a String instead. |
| 23:13 | <jmdyck> | (i.e., if the point is to reassure the reader about what _v_ is) |