Editorial: For CONTRIBUTING.md, add explicit references to patterns we've evolved over time
#10392
Conversation
domfarolino
changed the title
CONTRIBUTING.md, add explicit references to patterns we've passively evolved over timeCONTRIBUTING.md, add explicit references to patterns we've evolved over time
CONTRIBUTING.md
Outdated
| - **"If foo, then bar"** instead of "If foo, bar". [Example](https://github.com/whatwg/html/pull/10269#discussion_r1568114777). | ||
| - **"Abort these steps" vs "return"**. | ||
| - We've passively evolved the pattern of reserving "return" for exiting algorithms and methods, and "abort these steps" for terminating a set of substeps / [in parallel](https://html.spec.whatwg.org/C#in-parallel) steps without messing with the control flow of the "outer" procedure. See [this logic](https://github.com/WICG/portals/pull/138#discussion_r292649287), as well as https://github.com/whatwg/infra/issues/258 and https://github.com/whatwg/infra/pull/255. | ||
| - **Usage of positional, optional, and named[^1] (i.e., linkable) parameters**. See [this logic](https://docs.google.com/document/d/1yxnzjRDVmAR5CC9GcAyY448lBD0u0E98eUEMHDhx1Dw/edit?disco=AAAAeXYly54) for how to order and refer to these. |
There was a problem hiding this comment.
The ?disco=... link only goes to a comment for people with permission to add comments. (Yay Docs permissions.) I'd argue for inlining all the references-to-discussions into this document.
There was a problem hiding this comment.
+1 on inlining. And figuring out how to state it more generally.
Probably https://infra.spec.whatwg.org/#algorithm-params should be referenced from here. But that doesn't give too much guidance on when to use mandatory vs. named-mandatory vs. optional vs. named-optional.
I'm not sure how strong the guidance should be here, but the doc comment you link to is indeed a reasonable default for people to start from.
There was a problem hiding this comment.
Looking at this a little bit more, I'm not even sure that the current version of #navigate is consistent with the guidance in the Google doc (there seem to be no optional non-named/linkable parameters in that algorithm declaration, which honestly just seems for the best).
I've simplified this by linking to the infra link @domenic provided above and specifically calling out the fact that you must use named/linkable optional parameters whenever a callsite wants to pass in a later-positioned optional argument without earlier-positioned ones. I think that's reasonable advice, although I'm not sure it's really a. The alternative would be to just say use named params for all optional params, which I think I would prefer (we have too many algorithms that are impossible to audit the callsite/declaration conformance of, in part due to lack of linkability), but that's a bit heavy-handed so I'm not sure how others feel. WDYT about the current version?
CONTRIBUTING.md
Outdated
| - **"If foo, then bar"** instead of "If foo, bar". [Example](https://github.com/whatwg/html/pull/10269#discussion_r1568114777). | ||
| - **"Abort these steps" vs "return"**. | ||
| - We've passively evolved the pattern of reserving "return" for exiting algorithms and methods, and "abort these steps" for terminating a set of substeps / [in parallel](https://html.spec.whatwg.org/C#in-parallel) steps without messing with the control flow of the "outer" procedure. See [this logic](https://github.com/WICG/portals/pull/138#discussion_r292649287), as well as https://github.com/whatwg/infra/issues/258 and https://github.com/whatwg/infra/pull/255. | ||
| - **Usage of positional, optional, and named[^1] (i.e., linkable) parameters**. See [this logic](https://docs.google.com/document/d/1yxnzjRDVmAR5CC9GcAyY448lBD0u0E98eUEMHDhx1Dw/edit?disco=AAAAeXYly54) for how to order and refer to these. |
There was a problem hiding this comment.
+1 on inlining. And figuring out how to state it more generally.
Probably https://infra.spec.whatwg.org/#algorithm-params should be referenced from here. But that doesn't give too much guidance on when to use mandatory vs. named-mandatory vs. optional vs. named-optional.
I'm not sure how strong the guidance should be here, but the doc comment you link to is indeed a reasonable default for people to start from.
Co-authored-by: Jeffrey Yasskin <[email protected]>
Co-authored-by: Jeffrey Yasskin <[email protected]>
Co-authored-by: Jeffrey Yasskin <[email protected]>
Co-authored-by: Jeffrey Yasskin <[email protected]>
Co-authored-by: Jeffrey Yasskin <[email protected]>
Co-authored-by: Jeffrey Yasskin <[email protected]>
Recently I spoke with several people who were frustrated with style nits that editors would give them on PRs. I think part of this problem can be ameliorated by simply documenting several of these patterns that we've implicitly evolved over time, that seem to exist in the heads of only a few, so that newcomers have a better shot at writing the correct thing the first time.