cynthia
commented
1 year ago Discussed in our F2F today.
Historically, the principles as of today primarily serves the needs of the web (in terms of new proposals with antipatterns, which the principles attempts to address) and the spec authors who produce said proposals facing the web.
In principle, having our principles reflect the needs and propose best practices for a wide JavaScript audience would be a useful transition. However, it was difficult for us to converge on a direction that evolves the principles to serve a wider audience. As far as I see it, there are a couple ways to do this:
1) Address them as we find them (e.g., #435): There is an inherent risk that we will end up with inconsistent terminology and guidance across the document, resulting in a situation where we confuse audience from both ends. 2) Larger refactor/rewrite of current principles to consistently apply the scope change: As this is likely a large change, this would have to be done carefully, and likely in a setup where we'd be doing this in a setup where we can quickly review and land (e.g., a F2F meeting) - as the last time we did this the conflict resolution was a painful process due to the review taking longer than expected. 3) Spin up a separate principles document for generic JS and reference that for the JavaScript sections: This would be the easiest to spin up, but also would require coordination to ensure antipatterns and guidance for web platform quirks are in place.
It would be useful to know how non-browser facing audience perceives the document as it is today, in particular around where they feel the gaps are.
CC: @littledan for input.
Part of the discussion in the Tokyo F2F was around the fact that while most of our JS-related principles are more broadly applicable to JS APIs, they are worded only with Web APIs in mind.
For example, section 6 is applicable to all JS, yet many principles are very Web IDL - centric. E.g. 6.1. Attributes should behave like data properties. "Attributes" as a term is Web IDL centric, the JS term is "accessors", which is how these are implemented anyway. The principle itself talks about Web IDL before it even gets to the actual guidance. I submitted a PR ( https://github.com/w3ctag/design-principles/pull/435/files ) about what a more inclusive rephrasing could look like.
The way I see it, Web IDL in the context of these principles is largely an implementation detail. The principles should be about architecture and API design. The principles primarily guide API designers on what to do, not how to do it. As a thought experiment, if in the future, we moved towards a different language for describing Web Platform APIs, the document should still be equally valuable in making design decisions. It's fine to have guidance about Web IDL, but it should not be more prominent than the actual API design guidance.
De-emphasizing Web IDL on principles not specifically centered around it would not only make this document more inclusive for non-Web APIs (and thus make it easier to collaborate with TC39 on them), but it would also help in the developer version (#268).