Web プラットフォーム設計原則 — Web Platform Design Principles

1.1. 利用者の必要性を第一に置くこと（~~対象者の優先度）

~trade-offを為す必要がある場合、 常に，利用者の必要性を他のすべてより上に置くこと。 ◎ If a trade-off needs to be made, always put user needs above all.

類似に，~APIを設計し始めるときは、 当の~APIが取組もうと目指す利用者の必要性【！need】を理解して，それを文書化すること。 ◎ Similarly, when beginning to design an API, be sure to understand and document the user need that the API aims to address.

`~internetは末端-利用者のためにある＠~RFCx/rfc8890$： ~web~platformに為される どの変更も， `膨大な数の人々に影響する＠~ETHICAL-PRINCIPLES#allpeople$能性があり、 どの個人の生活にも根深い影響iがあり得る。 `RFC8890$r ◎ The internet is for end users: any change made to the web platform has the potential to affect vast numbers of people, and may have a profound impact on any person’s life. [RFC8890]

次も見よ ⇒＃ `§ ~webは、社会に害をもたらさない＠~ETHICAL-PRINCIPLES#noharm$ ／ `§ ~webは、各個人による制御と力を増強する＠~ETHICAL-PRINCIPLES#control$ ／ `RFC8890$r ◎ See also: • The web should not cause harm to society • The web must enhance individuals' control and power • [RFC8890]

1.2. ~web~pageは安全に訪問できるべきである

新たな特能を追加するときは、 利用者の期待 — ~web~pageを訪問することは、 一般に安全であること — を保全するように設計すること。 ◎ When adding new features, design them to preserve the user expectation that visiting a web page is generally safe.

~Webは、 その~hyperlinkされた構造に因んで命名された。 ~webが活発であり続けるためには、 利用者が次を期待-可能になる必要がある ⇒ 所与の どの~linkに対しても、 それをただ訪問しただけでは，［ 利用者の~computer~security／ 利用者の`~privacy＠~ETHICAL-PRINCIPLES#privacy$の本質的な側面 ］に対する含意は無い。 ◎ The Web is named for its hyperlinked structure. In order for the web to remain vibrant, users need to be able to expect that merely visiting any given link won’t have implications for the security of their computer, or for any essential aspects of their privacy.

例えば、 ある~APIが，どの~web~siteにも `支援技術の利用を検出する＠#do-not-expose-use-of-assistive-tech$ことを許容すると、［ どの~web~pageも，この私的な情報を検出し得る ］ようになるので，これらの技術の利用者は［ 未知な~web~pageを訪問するのは安全でない ］と感じるようになる。 ◎ For example, an API which allows any website to detect the use of assistive technologies may make users of these technologies feel unsafe visiting unknown web pages, since any web page may detect this private information.

利用者が安全性に現実的な期待を持てるならば、 彼らは［ ~Webに基づく技術, 他の技術 ］どちらにするか，~~情報を得た下で裁定を下せるようになる。 例えば，利用者は、 ~appを~installするより，~webに基づく食品注文~pageを利用する方を選ぶであろう — ~native~appを~installするのは、 ~web~pageを訪問するより~riskが高いので。 ◎ If users have a realistic expectation of safety, they can make informed decisions between Web-based technologies and other technologies. For example, users may choose to use a web-based food ordering page, rather than installing an app, since installing a native app is riskier than visiting a web page.

~web上の安全性の現実が利用者の期待に合致する方へ必ず向かうよう作業するため、 新たな特能を追加するときは，相補的な~approachをとれる： ◎ To work towards making sure the reality of safety on the web matches users' expectations, we can take complementary approaches when adding new features:

• 利用者は~UIを通して~Webを利用する — ~UIは、［ 利用者が期待するもの（および，しないもの）は何であるべきか ］が より明瞭になるよう，改善できる。 ◎ We can improve the user interfaces through which the Web is used to make it clearer what users of the Web should (and should not) expect;
• ~Webの技術的な土台は、 ~privacyに関する利用者の期待に合致するよう，変更できる。 ◎ We can change the technical foundations of the Web so that they match user expectations of privacy;
• 期待が もっと高かったなら，利用者にとって より良くなる事例を考慮できる。 そのような事例では、 技術的な［ 土台, 期待 ］どちらも変更しようと試行できる。 ◎ We can consider the cases where users would be better off if expectations were higher, and in those cases try to change both technical foundations and expectations.

新たな特能が安全性の~riskを導入する場合でも、 それが［ 利用者にとって、 同じ~taskを~web~page上で遂行する方が， ~native~appを~installするより安全になる ］ことを許容するならば， 利用者の安全性は総じて改善され得る。 しかしながら，この便益は、［ ~web~pageの安全性に適理な期待を有している利用者たち ］の共通な目標と比較検討される必要がある。 ◎ A new feature which introduces safety risks may still improve user safety overall, if it allows users to perform a task more safely on a web page than it would be for them to install a native app to do the same thing. However, this benefit needs to be weighed against the common goal of users having a reasonable expectation of safety on web pages.

次も見よ ⇒ `~securityと~privacyに関する自己-考査＠~SECQ$cite ◎ See also: • Security and Privacy Self-Review

1.3. 信用-済み~UIは信用に価するべきである

新たな特能が信用-済み~UIに影響iするかどうかを考慮すること。 ◎ Consider whether new features impact trusted user interfaces.

利用者は、［ ~URL~bar／~security指示子／許可~prompt ］などの信用-済み~UIに依存して，自身が誰とどうヤリトリしているかを理解する。 これらの信用-済み~UIは、 それらが供する情報が［ 本物であって，当の~web~siteにより［ 偽装されていない／乗取られていない ］こと ］を利用者が［ 信用する, `検証yする＠~ETHICAL-PRINCIPLES#verify$ ］ことを可能化するような仕方で，設計-可能でなければナラナイ。 ◎ Users depend on trusted user interfaces such as the address bar, security indicators and permission prompts, to understand who they are interacting with and how. These trusted user interfaces must be able to be designed in a way that enables users to trust and verify that the information they provide is genuine, and hasn’t been spoofed or hijacked by the website.

新たな特能が，信用-済み~UIを真似ることを信用-済みでない~UIに許容する場合、 利用者にとって，どの情報が信用に価するか理解するのは より困難になる。 ◎ If a new feature allows untrusted user interfaces to resemble trusted user interfaces, this makes it more difficult for users to understand what information is trustworthy.

1.4. 有意義な同意を利用者に依頼すること

有用な特能が利用者に害を及ぼす能性がある場合、 その特能の利用に対する`有意義な同意＠~ETHICAL-PRINCIPLES#control$emを利用者から得ること, および同意を利用者が効果的に拒否できるようにすること。 ◎ If a useful feature has the potential to cause harm to users, make sure that the user can give meaningful consent for that feature to be used, and that they can refuse consent effectively.

利用者から`有意義な同意^emを得るためには、 利用者にとって，次が可能にならなければナラナイ： ◎ In order to give meaningful consent, the user must:

• 何を~web~pageに許可する（しない）のか`理解する^strong。 ◎ understand what permission they may choose whether to grant the web page
• その許可を［ 是認する／拒否する ］ことを`効果的^strongに選ぶ。 ◎ be able to choose to give or refuse that permission effectively.

ある特能が利用者からの同意を要求するほど十分に強力であるが， 典型的な利用者に何を同意しているのか説明するのは不可能な場合、 それは，当の特能の設計を考慮し直す必要があろう兆候である。 ◎ If a feature is powerful enough to require user consent, but it’s impossible to explain to a typical user what they are consenting to, that’s a signal that you may need to reconsider the design of the feature.

ある許可~promptが示され，利用者が許可を是認しなかった場合、 ~web~pageは，利用者が同意を拒否したと信じたものを行えるようになるべきでない。 ◎ If a permission prompt is shown, and the user doesn’t grant permission, the Web page should not be able to do anything that the user believes they have refused consent for.

同意を依頼することにより，~web~pageが何の能力を［ 有するか／有さないか ］を利用者に伝えられれば、 利用者にとって`~webは安全である＠#safe-to-browse$確証は高まる。 しかしながら，新たな特能による`利用者の便益＠#priority-of-constituencies$は、 利用者に対する追加的な負担 — 各~特能に対し，~web~pageから要請される度に許可を是認するかどうか裁定する — を正当化しなければナラナイ。 ◎ By asking for consent, we can inform the user of what capabilities the web page does or doesn’t have, reinforcing their confidence that the web is safe. However, the user benefit of a new feature must justify the additional burden on users to decide whether to grant permission for each feature whenever it’s requested by a Web page.

次も見よ ⇒＃ `§ ~webは、~secureであり，人々の~privacyを尊重する＠~ETHICAL-PRINCIPLES#privacy$ ◎ See also: • Security and privacy are essential

1.5. 識別情報を文脈において適切に利用すること

人々が［ 様々な文脈の下で，~webに対し呈示している自身についての識別用の情報 ］に対する`制御＠~ETHICAL-PRINCIPLES#control$を彼らに与えること — それついて透明であること。 ◎ Give people control over the identifying information about themselves they are presenting in different contexts on the web, and be transparent about it.

“識別情報（ `identity^en ）” は、 多くの異なる仕方で理解され得る，複階的な概念である。 それは、 誰かが自身を［ どう呈示するか／どう見ているか ］を指すことも，自身が［ 他の人々／~group／団体 ］（順不同）とどう関係するかを指すこともあり、 その者が［ どう挙動するか／他者によりどう扱われるか ］（順不同）を決定し得る。 ~web~architectureにおける “識別情報” は、［ 識別子や, それに付された情報 ］を指す総称として利用されることが多い。 ◎ "Identity" is a complex concept that can be understood in many different ways. It can refer to how someone presents or sees themselves, how they relate to other people, groups, or institutions, and can determine how they behave or how they are treated by others. In web architecture, "identity" is often used as a shortcut to refer to identifiers, and the information attached to them.

［ 識別子や，それに付された ある個人についての~data ］を［ 利用する, あるいは それに依存する ］特能は、［ 単独の［ ~API／~system ］を超えて到達することが多い~privacy~risk ］を運ぶ。 これには、 受動的に生成された~data （例：~web上での彼らの挙動について）も， 能動的に収集された~data （例：彼らが ある~form内で埋めたもの）も含まれる。 ◎ Features that use or depend on identifiers and the attachment of data about a person to that identifier carry privacy risks which often reach beyond a single API or system. This includes data that has been passively generated (for example, about their behaviour on the web) as well as that which has been actively collected (for example, they have filled in a form).

そのような特能に対しては、 それが利用されることになる`文脈を理解する＠~PRIVACY-PRINCIPLES#identity$ベキである — それが［ ~webを成す他の特能と~~並行して，どう利用されることになるか ］も含めて。 利用者が`適切な同意を与えれる＠#consent$ようにすること。 ~APIが収集する~dataの量は`必要yな~~最小限になる＠~PRIVACY-PRINCIPLES#data-minimization$よう設計すること。 持続的な識別子が絶対的に必要yでない限り、 短期的かつ一時的な識別子を利用すること。 ◎ For such features, you should understand the context in which it will be used, including how it will be used alongside other features of the web. Make sure the user can give appropriate consent. Design APIs to collect the smallest amount of data necessary. Use short-lived, temporary identifiers unless a persistent identifier is absolutely necessary.

1.6. 全部的な範囲の装置と~platformを~supportすること（媒体からの独立性）

~web上の特能は、 アリな限り`多くの異なる＠~ETHICAL-PRINCIPLES#multi$［ 入力~装置／出力~装置／~screen~size／対話~mode／~platform／媒体 ］にまたがって働くことを確保すること。 ◎ As much as possible, ensure that features on the web work across different input and output [devices, screen sizes, interaction modes, platforms, and media] (https://www.w3.org/2001/tag/doc/ethical-web-principles/#multi).

~Webの主な価値の一つは、 極めて柔軟なことにある： ある~web~pageは、［ 多様な消費者~計算機で様々な~sizeの~screenで視られる／ 印刷される媒体を生成するために利用される／ 数多くの異なる仕方でヤリトリされる ］こともある。 新たな特能は、 ~web~platformの`既存の柔軟性＠~ETHICAL-PRINCIPLES#render$に合致するべきである。 ◎ One of the main values of the Web is that it’s extremely flexible: a Web page may be viewed on virtually any consumer computing device at a very wide range of screen sizes, may be used to generate printed media, and may be interacted with in a large number of different ways. New features should match the existing flexibility of the web platform.

特能はまた、［ それを利用する最も容易な仕方は，柔軟性を保守する ］ように設計されるべきである。 ◎ Features should also be designed so that the easiest way to use them maintains flexibility.

特能は、 ときには，一部の［ 実装／~platform ］では まだ可用でないこともある — 他では働くにもかかわらず。 そのような事例では、 当の特能は，［ 上品に失敗する, あるいは~polyfillするための~codeがアリになる ］ように設計されるベキである。 `§ 新たな特能は検出-可能になるべきである＠#feature-detect$ を見よ。 ◎ Sometimes features aren’t yet available on some implementations or platforms despite working on others. In these cases, features should be designed such that it is possible for code to gracefully fail or be polyfilled. See § 2.5 New features should be detectable.

1.7. 新たな能力は~careの下で追加すること

~webに新たな能力を追加するときは、 既存の［ 機能性／内容 ］を考慮すること。 ◎ Add new capabilities to the web with consideration of existing functionality and content.

~Webには、 追加を許容する拡張~地点が数多くある — 例えば、 `HTML$r `§ 拡張能＠~HTMLintroduction#extensibility$ を見よ。 ◎ The Web includes many extension points that allow for additions; see for example HTML § 1.7.3 Extensibility.

何かを追加する前に，既存の［ 類似な能力 ］との統合を考慮すること。 その結果，選好される設計~approachが［ 何かを追加するだけでは実装し得ないもの ］へ至る場合でも、 それはアリかもしれない — `§ 能力を［除去する／変更する］前に既存の用法を理解すること＠#removing-features$ を見よ。 ◎ Before adding items, consider integration with existing, similar capabilities. If this leads to a preferred design approach that cannot be implemented by only adding items, it might still be possible; see § 1.8 Remove or change capabilities only once you understand existing usage.

最初に検査することなく，［ 変更／除去 ］はアリでないとは見做さないこと。 ◎ Do not assume that a change or removal is impossible without first checking.＼ （以下重複） Before adding items, consider integration with existing, similar capabilities. If this leads to a preferred design approach that cannot be implemented by only adding items, it might still be possible; see § 1.8 Remove or change capabilities only once you understand existing usage. Do not assume that a change or removal is impossible without first checking.

1.8. 能力を［除去する／変更する］前に既存の用法を理解すること

機能性を［ 除去する／変更する ］ときは、 既存の内容との互換性を優先すること。 ◎ Prioritize compatibility with existing content when removing or changing functionality.

有意な量の内容が，特定0の挙動に依存するようになったなら、 その挙動を［ 除去する／変更する ］ことは忌避される。 特能や能力を［ 除去する／変更する ］ことは，アリだが、 まずは，［ 既存の内容に対する影響i ］の資質や視野を理解することが要求される。 これは、［ 既存の内容が当の特能をどう利用しているか ］について事実調査が要求されるかもしれない。 ◎ Once a significant amount of content has come to depend on a particular behavior, removing or changing that behavior is discouraged. Removing or changing features and capabilities is possible, but it first requires that the nature and scope of the impact on existing content is well understood. This might require research into how features are used by existing content.

既存の用法を理解する義務は、 内容が依拠している各~特能にも適用される。 これには、 実装の~bugと見なされるかもしれないような， ~vendorに~proprietaryな特能や挙動も含まれる。 ~web特能は、 仕様のみならず［ そのような特能を内容が どう利用するか ］によっても定義される。 ◎ The obligation to understand existing usage also applies to any features that content relies upon. This includes vendor-proprietary features and behavior that might be considered implementation bugs. Web features are not solely defined in specifications; they are also defined by how content uses those features.

1.9. ~webをより良いものにして残すこと

~web~platformに新たな能力を追加するときは、 ~platformが総じて改善される仕方で行うこと — 例えば、［ ~security／~privacy ］の脆弱性や~accessibilityの特性。 ~platformの一部に存在する欠陥を，新たな能力の中に［ 追加する／拡張する ］ための許諾として利用してはナラナイ — そうすると，~platformの品質は総じて劣化するので。 新たな~web能力は、 アリな所では，~platformの品質が総じて改善されるように築くこと。 ◎ As you add new capabilities to the web platform, do so in a way that improves the overall platform, for example its security or privacy vulnerabilities, or accessibility characteristics. The existence of a defect in one part of the platform must not be used as a license for adding or extending such defect into new capabilities and thereby further decreasing the overall platform quality. Where possible, build new web capabilities that improve the overall platform quality.

~web~platformの各部は、 独立に発展する。 ある種の~web技術に今在る課題は、 後続な~~版において修正され得る。 これらの課題を重ねて持ち込むと、 修正するのは，さらに困難になる。 この原則を固守することで、 ~platformの品質は，時を経るに伴い総じて改善されるようになる。 ◎ Parts of the web platform evolve independently. Issues that are present with a certain web technology now may be fixed in a subsequent iteration. Duplicating these issues makes fixing them more difficult. By adhering to this principle we can make sure overall platform quality improves over time.

1.10. 利用者~dataを最小~化すること

特能は、［ その利用者の目標を遂げるために必要yな最小な量の~data ］で働くように設計すること。 ◎ Design features to work with the minimum amount of data necessary to carry out their users' goals.

`~dataの最小~化＠~PRIVACY-PRINCIPLES#data-minimization$は、 ~dataが不適切に［ 開示される／誤って利用される ］~riskを制限する。 ◎ Data minimization limits the risks of data being inappropriately disclosed or misused.

~Web~APIは、 ~siteにとって，［ 少ない量の~data — あるいは，より［ 細やかな／特定な ］【言い換えれば、当の~API用に最適化された】~data — を［ 要請する／収集する／伝送する ］（順不同） ］方が［ より［ 汎用な／~bulkな ］~dataで作業する ］よりも容易になるように設計すること。 ~APIは、 ~siteへ通信される~data — 特に，`個人-~data＠~PRIVACY-PRINCIPLES#dfn-data$ — に対する［ 細やかさ, 利用者-制御 ］も供するベキである。 追加的な機能性に追加的な~dataが要求されるときは、 ~APIは，それを利用者-同意（例：許可~promptや利用者-作動化）の~subjectにすることで可能化できる。 ◎ Design Web APIs to make it easier for sites to request, collect, and/or transmit a small amount of data, or more granular or specific data, than it is to work with more generic or bulk data. APIs should also provide granularity and user controls, in particular over personal data, that is communicated to sites. When additional functionality requires additional data, APIs can enable this subject to user consent (e.g., a permission prompt or user activation).

2.1. 単純な解決策を選好すること

取組もうと意図する`利用者の必要性＠#priority-of-constituencies$に対し， 単純な解決策を探す努力を怠らないこと。 ◎ Look hard for simple solutions to the user needs you intend to address.

一般に、 複階的な解決策より単純な解決策の方が良い — それを見出す方が難しいこともあろうが。 特能は単純な方が ⇒＃ ~UAにとって実装して~testするのは容易になる／ 相互運用可能になる見込みが高い／ 作者が理解するのは容易になる ◎ Simple solutions are generally better than complex solutions, although they may be harder to find. Simpler features are easier for user agents to implement and test, more likely to be interoperable, and easier for authors to understand.＼

とりわけ、 当の特能を［ 最も共通な利用事例を容易に成遂げる ］よう設計することが重要である。 ◎ It is especially important to design your feature so that the most common use cases are easy to accomplish.

`利用者の必要性＠#priority-of-constituencies$をきちんと定義すること — そうすれば、 視野が次第に逸れていくこと（ `scope creep^en ）は避けれるようになる。 また、 当の~APIが，すべての利用者の必要性を実際に満たすようにすること。 もちろん［ 複階的／稀 ］な利用事例も解くに価するが、 それらの解決策は利用するのが複雑なこともある。 `Alan Kay^en 氏が言ったとおり， “`simple things should be simple, complex things should be possible^en” 【 “単純なものは単純にしつつ，複階的なものもアリになるべきである” 】。 ◎ Make sure that your user needs are well-defined. This allows you to avoid scope creep, and make sure that your API does actually meet the needs of all users. Of course, complex or rare use cases are also worth solving, though their solutions may be more complicated to use. As Alan Kay said, "simple things should be simple, complex things should be possible."

共通な事例は単純なことが多いが、 共通度と複階度は，常に相関するとは限らないことに注意。 ◎ Do note however that while common cases are often simple, commonality and complexity are not always correlated.

次も見よ ⇒ `LEAST-POWER$r ◎ See also: • [LEAST-POWER]

2.2. 高~levelな~APIと低~levelな~APIの~tradeoffを考慮すること

高~levelな~APIは、 `利用者に利する＠#priority-of-constituencies$ために — ［ ~accessibility／~privacy／利便性 ］を確保するためなど — 様々な仕方で介入する能を より多く~UAに許容する。 ◎ High-level APIs allow user agents more ability to intervene in various ways on behalf of the user, such as to ensure accessibility, privacy, or usability.

低~levelな~APIには、［ 高~levelな~APIが，時を経て得られた用法~patternから組織的に形作れる ］よう，作者に実験n用の部屋を与えるゆとりがある。 それはまた、［ より高~levelな~APIでは必要十分でない，目の前の利用事例 ］のための逃げ道を供する。 ◎ Low-level APIs afford authors room for experimentation so that high level APIs can organically emerge from usage patterns over time. They also provide an escape hatch when the higher-level API is not adequate for the use case at hand.

より低~levelな構築部品は、 ~Web~APIとして公開できないこともある。 アリな理由として，［ 利用者の~securityと~privacyを保全する／ ~Web~APIを特定の~hardware実装に束ねるのを避ける ］ことが挙げられる。 しかしながら，高~levelな~APIは、［ アリなときは，より低~levelな~APIに基づく構築部品の用語 ］で設計されるべきである。 これは、［ 高~levelな~APIは，どうなる必要があるか ］に関する裁定を手引きするものになろう。 ◎ Lower level building blocks cannot always be exposed as Web APIs. A few possible reasons for this are to preserve the user’s security and privacy, or to avoid tying Web APIs to specific hardware implementations. However, high level APIs should be designed in terms of building blocks over lower level APIs whenever possible. This may guide decisions on how high level the API needs to be.

きちんと層~化された解決策は、［ その力に比して，利用の難易度がひどく上がることはない ］ことを確保するべきである — 利用-事例の複階性が少し増すだけで~codeの複階性が大きく増えないよう。 ◎ A well-layered solution should ensure continuity of the ease-of-use vs power tradeoff curve and avoid sharp cliffs where a small amount of incremental use case complexity results in a large increase of code complexity.

2.3. よく考して命名すること

【！Name APIs with care.】 ~APIをきちんと命名しておけば、 作者が それを正しく利用するのは，ずっと容易になる。 ◎ Name APIs with care. Naming APIs well makes it much easier for authors to use them correctly.

命名に特有な，より詳細な指導は、 `§ 命名~原則＠#naming-is-hard$を見よ。 ◎ See the more detailed Naming principles section for specific guidance on naming.

2.4. 他所と一貫すること

~APIの設計における先例を考慮して，それと一貫するよう努めることは、 良い実施である。 ◎ It is good practice to consider precedent in the design of your API and to try to be consistent with it.

既存の先例の利便性が拙い場合、 ~APIの［ 人間工学, 一貫性 ］両面は対立することが多い。 一部の事例では，一貫性を破ってでも利便性を改善することがイミを成すが、 その改善は，そうすることを有意に正当化するものであるべきである。 ◎ There is often a tension between API ergonomics and consistency, when existing precedent is of poor usability. In some cases it makes sense to break consistency to improve usability, but the improvement should be very significant to justify this.

~web~platformは、 時を経て次第に発展してきたので， 相反な複数の競合している先例があることも多い。 どの先例に従うかは、 次を織り込む下で比較検討できる： ◎ Since the web platform has gradually evolved over time, there are often multiple conflicting precedents which are mutually exclusive. You can weigh which precedent to follow by taking into account＼

• 普及度（他がすべて等しいなら，より普及な先例に従う） ◎ prevalence (all else being equal, follow the more popular precedent),＼
• 人間工学（他がすべて等しいなら，より利用-可能な先例に従う） ◎ API ergonomics (all else being equal, follow the more usable precedent),＼
• ~APIの齢（他がすべて等しいなら，より新たな先例に従う） ◎ and API age (all else being equal, follow the newer precedent).

［ `内部~一貫性^em, `外部~一貫性^em ］も対立することが多い。 前者は，当の~systemの他所すべてとの一貫性であり、 後者は，外の世界の他所すべてとの一貫性である。 それは、 ~web~platformにおいては，次に挙げる 3 つの層で顕在化されよう： ◎ There is often a tension between internal and external consistency. Internal consistency is consistency with the rest of the system, whereas external consistency is consistency with the rest of the world. In the web platform, that might materialize in three layers:＼

• 当の~APIが所属する技術（例：~CSS）との一貫性 ◎ consistency within the technology the API belongs to (e.g. CSS),＼
• ~web~platformの他所すべてとの一貫性 ◎ consistency with the rest of the web platform,＼
• 一部の事例 — 当の~APIが［ 特定0の特化された外側の領分 ］に関係する事例 — では、 外部な先例との一貫性 ◎ and in some cases external precedent, when the API relates to a particular specialized outside domain.＼

これらの事例では、［ 大多数の利用者は，どれに該当するか ］を考慮することが有用になる。 ほとんどの~APIは、 それが ある技術の下で定義されるならば，~target利用者は その技術に馴染みな者たちなので、 その技術との一貫性を支持する方が無難になる。 ◎ In those cases, it is useful to consider what the majority of users will be. Since for most APIs the target user is someone who is familiar with the technology they are defined in, err on the side of favoring consistency with that.

別々な節として， `§ 一貫するよう命名すること＠#naming-consistency$もある。 ◎ There is also a separate section on naming consistency.

2.5. 新たな特能は検出-可能になるべきである

当の特能が可用でないときも，~web内容が それを上品に取扱えるよう、 可用かどうかを作者が~program的に検出する仕方を供すること。 ◎ Provide a way for authors to programmatically detect whether your feature is available, so that web content may gracefully handle the feature not being present.

既存の特能は、 いくつかの理由から，~pageにて可用でないこともある。 共通的な理由には、 次の 2 つが挙げられる ⇒＃ まだ実装されていない ／ `~secureな文脈＠#secure-context$内でしか可用でない ◎ An existing feature may not be available on a page for a number of reasons. Two of the more common reasons are because it hasn’t been implemented yet, or because it’s only available in secure contexts.

作者にとって［ 各~局面を取扱うために異なる~codeを書する必要 ］は生じるべきでない。 この仕方により、 作者が一つの局面しか［ 知らない／~careしない ］場合でも，~codeは それらすべてを取扱うことになる。 ◎ Authors shouldn’t need to write different code to handle each scenario. That way, even if an author only knows or cares about one scenario, the code will handle all of them.

注記： ある特能が［ 可用ではあるが、 要求される装置が無いため，その利用は実現可能でない ］ときは、 特能が可用であることを公開することに加え， 装置は可用でないことも検出する別々な仕方もある方が良い。 これは、［ 装置が可用でないとき, 特能が可用でないとき ］の取扱いを違えることを作者に許容する — 例えば、 装置を［ 前者のときは接続する／後者のときは可能化する ］よう利用者に示唆するなど。 ◎ When a feature is available but isn’t feasible to use because a required device isn’t present, it’s better to expose that the feature is available and have a separate way to detect that the device isn’t. This allows authors to handle a device not being available differently from the feature not being available, for example by suggesting the user connect or enable the device.

`§ 装置を［選定する／列挙する］~APIを公開するときの注意点＠#device-enumeration$ を見よ。 ◎ See § 9.2 Use care when exposing APIs for selecting or enumerating devices.

特能は、 常に，作者が~JSから検出-可能にするべきである。 一部の事例では、 特能は，それが利用される言語で検出-可能になるべきである （~CSSにおける `supports$at など）。 ◎ Authors should always be able to detect a feature from JavaScript, and in some cases the feature should also be detectable in the language where it’s used (such as @supports in CSS).

一部の事例では、 特能~検出を許容するのは`適切でないこともある^strong。 特能が検出-可能になるべきかどうかは、 当の特能に対する `利用者の必要性＠#priority-of-constituencies$ に基づく — 特能~検出が可用であること自体が［ 利用者の必要／設計~原則 ］に抵触する場合、 特能~検出は~supportされるべきでない。 ◎ In some cases, it may not be appropriate to allow feature detection. Whether the feature should be detectable or not should be based on the user need for the feature: if there is a user need or design principle which would fail if feature detection were available for the feature, then you should not support feature detection.

また，ある特能が一般に開発者に公開されない場合、 特能~検出を~supportするのは適切にならない。 例えば，私的~閲覧~modeは、 ~web仕様において認識される概念であるが，作者には公開されない。 私的~閲覧~modeに対する特能~検出は、 それ自体が利用者の必要性に反するので，~supportされてはナラナイ。 ◎ Also, if a feature is generally not exposed to developers, it is not appropriate to support feature detection. For example, private browsing mode is a concept which is recognised in web specifications, but not exposed to authors. For private browsing mode to support the user’s needs, it must not be feature detected.

次も見よ ⇒＃ `§ 私的~閲覧~mode下にあることを露呈しないこと＠#do-not-expose-use-of-private-browsing-mode$／ `§ 支援技術が利用-中にあることを露呈しないこと＠#do-not-expose-use-of-assistive-tech$／ `§ 新たな特能は~secureな文脈に制限することを考慮すること＠#secure-context$ ◎ See also: • § 2.7 Don’t reveal that private browsing mode is engaged • § 2.9 Don’t reveal that assistive technologies are being used • § 2.6 Consider limiting new features to secure contexts

2.6. 新たな特能は~secureな文脈に制限することを考慮すること

当の特能が［ ~secureな文脈にしか無い［ 認証／完全性／機密性 ］を伴わない限り，利用者に~riskを突きつける ］ことになる場合、 常に~secureな文脈に制限すること。 ◎ Always limit your feature to secure contexts if it would pose a risk to the user without the authentication, integrity, or confidentiality that’s present only in secure contexts.

他の特能に対しては、 ~~過去および~~現在の~TAG~memberたちは，一般的な助言について総意には達しなかった： ◎ For other features, TAG members past and present haven’t reached consensus on general advice.＼

• 一部の者は、 新たな特能（既存の特能に対する追加~以外の特能）は，［ すべて，~secureな文脈に制限されるべきである ］と予見する。 これは，~HTTPSの利用を促すことになり、 一般に，利用者にとって より~secureになる助けになる。 ◎ Some believe that all new features (other than features which are additions to existing features) should be limited to secure contexts. This would help encourage the use of HTTPS, helping users be more secure in general.
• 他の者は、 特能は，［［ ~security／~privacy ］に既知な影響iがある場合に限り，~secureな文脈に制限されるべきである ］と予見する。 これは、［［ 利用者の［ ~security／~privacy ］に影響iしない新たな特能 ］の利点を採るような~web~page ］を作成するときの敷居を低くする。 ◎ Others believe that features should only be limited to secure contexts if they have a known security or privacy impact. This lowers the barrier to entry for creating web pages that take advantage of new features which don’t impact user security or privacy.

2.7. 私的~閲覧~mode下にあることを露呈しないこと

当の特能は、 私的~閲覧~modeを検出する仕方を作者に与えないこと。 ◎ Make sure that your feature doesn’t give authors a way to detect private browsing mode.

一部の人々は、 `私的~閲覧~mode＠https://www.w3.org/2001/tag/doc/private-browsing-modes/$を利用して，自前の個人的な安全性を保護する。 このことから，誰かが私的~閲覧~modeを利用している事実は、 その者についての `敏感な情報＠~SECQ#sensitive-data$になり得る。 この情報は、 その者に力を持つ他者 （雇用者, 親権者, ~partner, `国家権力＠~ETHICAL-PRINCIPLES#expression$（ `state actor^en ） など） が制御している~web~siteに露呈された場合には， `人々を害する＠~ETHICAL-PRINCIPLES#noharm$こともある。 ◎ Some people use private browsing mode to protect their own personal safety. Because of this, the fact that someone is using private browsing mode may be sensitive information about them. This information may harm people if it is revealed to a web site controlled by others who have power over them (such as employers, parents, partners, or state actors).

そのような危険性がある下では、 ~web~siteは，私的~閲覧~mode下にあることを検出-可能になるべきでない。 ◎ Given such dangers, websites should not be able to detect that private browsing mode is engaged.

次も見よ ⇒＃ `§ ~webは、~secureであり，人々の~privacyを尊重する＠~ETHICAL-PRINCIPLES#privacy$／ `§ 当の特能は、下層の~platformについての情報を生成元に公開するか？＠~SECQ#underlying-platform-data$／ `§ 私的~閲覧~modeにおいて，~APIがどう挙動するべきか考慮すること＠#private-browsing-mode$ ◎ See also: • Security and privacy are essential • What data does this specification expose to an origin? • § 2.8 Consider how your API should behave in private browsing mode

2.8. 私的~閲覧~modeにおいて，~APIがどう挙動するべきか考慮すること

必要yなら、 当の~APIの挙動は，私的~閲覧~modeにおいて どう異なるべきかを指定すること。 ◎ If necessary, specify how your API should behave differently in private browsing mode.

例えば，当の~APIが［ 一人の利用者による［ 私的~閲覧~mode内での活動, その外での活動 ］を相関することを誰かに許容することになる情報 ］を露呈することになる場合、 アリな`軽減策＠~SECQ#mitigations$を考慮すること — 次に挙げるものなど： ◎ For example, if your API would reveal information that would allow someone to correlate a single user’s activity both in and out of private browsing mode, consider possible mitigations such as＼

• 【相関を妨げるような】~noiseを導入する。 ◎ introducing noise,＼
• 許可~promptを利用して，当の利用者に加的な情報を与える — 利用者が，この追跡に有意義に同意する助けになるよう （`§ 有意義な同意を利用者に依頼すること＠#consent$を見よ）。 ◎ or using permission prompts to give the user extra information to help them meaningfully consent to this tracking (see § 1.4 Ask users for meaningful consent).

私的~閲覧~modeは、［ 利用者による私的~閲覧の形跡を利用者の機器に残さない ］ように~webを閲覧することを，利用者に可能化する。 したがって， ~client側~storageを供する~APIは、［ 私的~閲覧~mode下にある間に格納された~data ］を その~modeから離れた後にも持続するべきでない。 これは、［ 検出-可能な~APIにおける いかなる相違も，当の~siteに露呈しない ］ように行えるし，行うべきである。 ◎ Private browsing modes enable users to browse the web without leaving any trace of their private browsing on their device. Therefore, APIs which provide client-side storage should not persist data stored while private browsing mode is engaged after it’s disengaged. This can and should be done without revealing any detectable API differences to the site.

次も見よ ⇒＃ `§ 私的~閲覧~mode下にあることを露呈しないこと＠#do-not-expose-use-of-private-browsing-mode$／ `§ 当の特能は、複数の閲覧~sessionにわたって持続する新たな状態を生成元~用に導入するか？＠~SECQ#persistent-origin-specific-state$／ `§ 当の特能は、~browserの私的~閲覧~modeの文脈においてどう働くか？＠~SECQ#private-browsing$ ◎ See also: • § 2.7 Don’t reveal that private browsing mode is engaged • Does this specification introduce new state for an origin that persists across browsing sessions? • Security and privacy self review: Private Browsing

2.9. 支援技術が利用-中にあることを露呈しないこと

当の~APIは、 利用者が支援技術を利用していることを［ 利用者の同意を経ることなく検出する仕方 ］を作者に供さないこと。 ◎ Make sure that your API doesn’t provide a way for authors to detect that a user is using assistive technology without the user’s consent.

`~web~platformは障害を伴う人々からも~access可能にしなければナラナイ＠~ETHICAL-PRINCIPLES#allpeople$。 ある~siteが利用者が支援技術を利用していることを検出できた場合、 その~siteは，自身が供する~serviceへの利用者による~accessを［ 否認-／制約- ］し得ることになる。 ◎ The web platform must be accessible to people with disabilities. If a site can detect that a user is using an assistive technology, that site can deny or restrict the user’s access to the services it provides.

支援技術を用立てる人々は、 `社会の脆弱な~member＠~ETHICAL-PRINCIPLES#noharm$ であることが多い。 彼らによる支援技術の利用は、 彼らについての`敏感な情報＠~SECQ#sensitive-data$である。 ある~APIが，この情報への~accessを`利用者の同意＠#consent$を経ることなく供する場合、 この敏感な情報は，彼らを害そうと望むかもしれない他者 （`国家権力＠~ETHICAL-PRINCIPLES#expression$も含む） に露呈され得る。 ◎ People who make use of assistive technologies are often vulnerable members of society; their use of assistive technologies is sensitive information about them. If an API provides access to this information without the user’s consent, this sensitive information may be revealed to others (including state actors) who may wish them harm.

ときには、 人々は［ 支援技術の利用者~用に利用者~体験を改善しようと目指す特能 ］を提案するが，それは［ 副作用として利用者の支援技術の利用を露呈する ］ことになろう。 これらには，きちんとした意図nがあるが、 `§ ~web~pageは安全に訪問できるべきである＠#safe-to-browse$ に違反するので，代替な解決策を見出さなければナラナイ。 ◎ Sometimes people propose features which aim to improve the user experience for users of assistive technology, but which would reveal the user’s use of assistive technology as a side effect. While these are well intentioned, they violate § 1.2 It should be safe to visit a web page, so alternative solutions must be found.

次も見よ ⇒＃ `~Web技術~accessibility指針＠https://w3c.github.io/apa/fast/$cite `§ ~webは、~secureであり，人々の~privacyを尊重する＠~ETHICAL-PRINCIPLES#privacy$／ `§ 当の特能は、下層の~platformについての情報を生成元に公開するか？＠~SECQ#underlying-platform-data$ ◎ See also: • Web Technology Accessibility Guidelines • Security and privacy are essential • What data does this specification expose to an origin?

2.10. 強力な~APIには、利用者-作動化を要求すること

一部の強力~APIは、 次に挙げる いずれかを行い得る： ◎ Some powerful APIs can＼

• 押付けな~UIを生産する （例：音声を自動-再生する） ◎ produce intrusive UI (eg. auto-playing audio),＼
• 利用者~dataを【~web~pageに】公開する （例：~clipboardとヤリトリする） ◎ expose user data (eg. interacting with the clipboard),＼
• 利用者に対する明白な指示子を伴わずに背景~活動を遂行する （例：局所~storageへ~accessする） ◎ perform a background activity without an obvious indicator to the user (eg. accessing local storage),＼
• `信用-済み~UI＠#trusted-ui$とヤリトリするよう利用者に~promptする （例：許可~prompt, 機器~hardware特能） ◎ or prompt the user to interact with trusted UI (eg. permission prompts, device hardware features).＼

これらの~APIが機能するためには、 利用者の意図nを成す何らかの指示 （`利用者-作動化^strongなど） を要求するよう設計されるベキである。 これは、 利用者が当の~web~pageに対し意図的にヤリトリしていることを指示する。 ◎ These APIs should be designed to require some indication of user intention (such as user activation) in order to function. This indicates that the user is intentionally interacting with the web page in question.

利用者-作動化は、 ~HTML標準にて，`詳細に定義される＠~HTMLinteraction#tracking-user-activation$。 利用者-作動化が生じる必要があるのは，次のうちどれになるか裁定するときは、 当の~APIによる［ 利用者~体験に対する効果，利用者に呈示される~risk ］について考するベキである ⇒＃ 総じて一回~限り（`居残な＠~HTMLinteraction#sticky-activation-gated-api$）／ 周期的（`一過な＠~HTMLinteraction#transient-activation-gated-api$）／ 各~API~callにつき一回（`一過に消費する＠~HTMLinteraction#activation-consuming-api$） ◎ User activation is defined in detail in the HTML standard. You should think about the effect your API has on the user experience, as well as any risks presented to the user, when deciding whether user activation needs to only occur once overall (sticky), periodically (transient) or once per API call (transient consuming).

利用者-作動化は、 多くの事例で必要yであるが， 侵害的な挙動から利用者を保護するに`足るとは限らない^em — `有意義な同意＠#consent$を探求することもまた重要であることに注意。 ◎ Note that while user activation is in many cases necessary, it is not always sufficient to protect users from invasive behaviours, and seeking meaningful consent is also important.

2.11. 全部的に作動中でない~BF~cacheされた文書を~supportすること

アリなら、 当の特能が ~BF~cacheされた【`~BF~cache$に格納された】`全部的に作動中$でない文書において，どう挙動するかを指定すること。 ◎ Specify how your feature behaves in non-fully active BFCached (Back/forward cached) documents if possible.

当の特能が，次に挙げるいずれかの分類に該当する`何か^strongを行う場合： ◎ If your feature does anything that falls into the following categories:

• “外側” から文書とヤリトリする （例：ある文書へ情報を送信する） ◎ Interacts with a document from the "outside" (e.g. sends information to a document)
• 文書~間での［ ヤリトリ／資源の共有 ］をアリにする （例：~lockを保持する） ◎ Makes cross-document interaction/resource sharing possible (e.g. holding locks)
• 文書が［ 利用者により他所へ~navigateされた／ 【利用者が履歴を辿った結果】復旧された ］後に［ `全部的に作動中$でない~BF~cacheされた状態 ］に保たれたとき， 当の文書は（破壊される代わりに）~~不正に機能し得る （例：当の文書~内に保存された状態は、 複数回の~naviにわたらないものと期待されている） ◎ May malfunction when a document is kept in a non-fully active BFCached state (instead of getting destroyed) after the user navigates away from it or gets restored (e.g. expects that a state saved in the document won’t span multiple navigations)

当の特能が~BF~cacheされた`全部的に作動中$でない文書でどう働くかを［ `~BF~cacheされた文書の~support法＠~BFCACHE$cite 手引きにおける指針 ］に従って指定すること。 ◎ Specify how your feature works with non-fully active BFCached documents, following the guidelines in the Supporting BFCached Documents guide.

注記： 文書は、 ~BF~cache法に関係しない他の理由で`全部的に作動中$でなくなることもアル — 当の文書を保持している `iframe$e が切離されたときなど。 この指導は、 `~BF~cache$が孕まれている事例に限られ， そのような事例には関連しない。 ◎ Note: It is possible for a document to become non-fully active for other reasons not related to BFcaching, such as when the iframe holding the document gets detached. This guidance only focuses on the case where BFCache is involved, and not other cases that might cause a document to become non-fully active.

2.12. 第三者-主体~toolとの互換性より利便性を優先すること

新たな特能を設計するときは、 第三者-主体~tool群との互換性よりも，利便性を首な目標とすること。 ◎ Design new features with usability as the primary goal, and compatibility with third-party tooling as a secondary goal.

~web~platformは、 幅広い~tool群が成す~ecosystemから，より容易かつ速い開発を手助けする便益を得ている。 今後、［ ~web~platform特能の構文が第三者-主体~toolのそれと競合して，非互換化の原因になる ］ことは，幾度となくあろう。 第三者-主体~toolは，新たな~web~platform特能の原型に利用されることが多いので、 このことは，とりわけ共通的にある。 ◎ The web platform benefits from a wide ecosystem of tooling to facilitate easier and faster development. A lot of the time, the syntax of an upcoming web platform feature may conflict with that of a third-party tool causing breakage. This is especially common as third-party tools are often used to prototype new web platform features.

~web~platform特能は、 一般に，ほとんどの第三者-主体~toolよりずっと長く残る。 なので、 それらに最適な［ 構文と機能性 ］を与える優先度は高くするべきである。 ◎ In general, web platform features last a lot longer than most third-party tools, and thus giving them the optimal syntax and functionality should be of high priority.

一部の事例では、 そのような競合は，あまりに多くの~web~siteに問題を導入する結果、 衝突を避けるため，特能の構文を設計し直す必要が生じる。 ◎ In some cases, the conflict will introduce problems across a large number of web sites, necessitating the feature’s syntax to be redesigned to avoid clashes.

しかしながら、 これらの事例は，例外とされるべきである。 ◎ However, these cases should be exceptions.

新たな構文で第三者-主体~toolを非互換化するかどうか裁定するにあたって考慮する要因は、 非互換化の著しさ, 第三者-主体~toolの普及度合いの他にも，いくつもある。 ◎ When deciding whether to break third party tools with new syntax, there are several factors to consider, such as severity of the breakage, popularity of the third party tool, and many more.

場合によっては、［ 第三者-主体~toolを非互換化するのを避けるために，当の特能の構文が変更された ］とする場合に［ ~web~platform特能の利便性は，どう著しく妥協されることになるか ］が，最も重要な要因になる。 類似な利便性を成すいくつかの代替が考慮されている場合、 通例的には，第三者-主体~toolのうち簡便でないものほど優先度を下げることが好ましい。 ◎ Possibly the most important factor is how severely would the usability of the web platform feature be compromised if its syntax was changed to avoid breaking the third party tool? If several alternatives of similar usability are being considered, it is usually preferable to prioritize the ones that inconvenience third party tools the least.

しかしながら、 第三者-主体~toolを非互換化するのを避けることが，特能の利便性に`有意^emな負な影響iへ導く場合、 それが受容-可能な~tradeoffになることは稀にしかない — 生きた~web~siteに有意な非互換化をもたらす場合を除けば。 ◎ However, if avoiding breaking the third party tool would lead to a significant negative impact on of the feature’s usability, that is rarely an acceptable tradeoff, unless it causes significant breakage of live websites.

言語は、 将来における そのような~dilemmaを抑制するよう，作者が［ 将来の~native機能性を非互換化することなく，言語を拡張する ］ために利用できる拡張能のための仕組みも供するべきである。 ◎ Languages should also provide mechanisms for extensibility that authors can use to extend the language without breaking future native functionality, to reduce such dilemmas in the future.

3.1. 類似な機能性（のみ）を備える属性の名前を再利用すること

~HTML属性を通して指定される特能を追加している場合、 別の要素に［ 類似な機能性を指定する既存の属性~名 ］が在るかどうか検査すること。 既存の属性~名を再利用することは、 次を意味する ⇒＃ 作者は既存の知識を用立てれる／ 複数の言語にわたって`一貫性＠#consistency$を保守する／ 語彙を少なく保つ ◎ If you are adding a feature that is specified through an HTML attribute, check if there is an existing attribute name on another element that specifies similar functionality. Re-using an existing attribute name means authors can utilize existing knowledge, maintains consistency across the language, and keeps its vocabulary small.

既存の属性を再利用する場合、 その構文は，既存の属性の構文にアリな限り近づけるよう努めること。 ◎ If you do re-use an existing attribute, try to keep its syntax as close as possible to the syntax of the existing attribute.

逆も適用される ⇒ 追加している機能性が既存の属性と`類似しない^strong場合には、 既存の属性~名を`再利用しない^strongこと。 ◎ The inverse also applies: do not re-use an existing attribute name if the functionality you are adding is not similar to that of the existing attribute.

3.2. 短い~list用には~spaceで分離された値たちをとる属性を, より長い~list用には別々な要素からなる~listを利用すること

ある要素についての~metadataを［ 値たちが成す~list ］として指定するときの共通な実施は、 ~spaceで分離された~listを利用した上で， それを `DOMTokenList$I として公開することである。 ◎ When specifying metadata about an element that can be a list of values, common practice is to use a space-separated list and expose it as a DOMTokenList.

~web~platformの他の各部との一貫性は重要である — これが，［ 値どうしを別の文字を利用して分離する ］ことを意味する場合でも。 ◎ Consistency with other parts of the Web Platform is important, even if this means using another character to separate values.

構文に関わらず、 属性は，値たちが成す~listが短い場合に限り利用するベキである。 より長い~list用には、 ある属性~内に~list全体を埋込むことは忌避される。 代わりに，現在の実施は、 各~list~item（および それについての~metadata）を別々な要素を利用して表現することである。 これらの要素は、 当の要素の子~群を成すようにすることも，属性を通して~linkすることもできる。 ◎ Regardless of syntax, attributes should only be used for short lists of values. For longer lists, embedding the entire list in an attribute is discouraged. Instead, current practice is to use separate elements to represent the list items (and any metadata about them). These elements could either be children of the element in question, or linked through an attribute.

稀な~instanceにおいては、 他の~tradeoffが必要yである。 ◎ In rare instances, other tradeoffs are necessary.

3.3. ~HTML構文解析器を静止させないこと

当の設計は、 次を確保すること ⇒ ~HTML構文解析器に［ 外部~資源を取扱うために静止する ］よう要求しない。 ◎ Ensure that your design does not require HTML parser to pause to handle external resources.

~browserは，~pageを構文解析するに伴い、 当の~pageに必要な~assetを発見して，各~assetに対し［ 並列的に読込むべきかどうか，優先度を解明する ］ことになる。 そのような構文解析は、 ある資源が後続な資源の発見を阻む場合に妨害され得る。 このことは： 最悪な場合、 ~browserは［ 各~itemを並列的ではなく順番に~downloadする ］ことを意味する。 最善な場合、 ~browserは［ 投機的な構文解析に基づいて~downloadを~queueする ］ことを意味する — それは、 不正であると判明することもある。 ◎ As a page parses, the browser discovers assets that the page needs, and figures out a priority in which they should be loaded in parallel. Such parsing can be disrupted by a resource which blocks the discovery of subsequent resources. At worst, it means the browser downloads items in series rather than parallel. At best, it means the browser queues downloads based on speculative parsing, which may turn out to be incorrect.

ある特能が構文解析器を阻むのは、 一般に［ 追加的な内容を後続な内容より前に構文解析器の中へ投入したい ］と求めるからである。 旧来の `<script src="…">^c 要素の事例は、 これに該当し， `document.write(…)^c を利用して構文解析器の中へ何かを注入し得る。 上述した処理能の課題に因り、 新たな特能は，これを行なってはナラナイ。 ◎ Features that block the parser generally do so because they want to feed additional content into the parser before subsequent content. This is the case of legacy <script src="…"> elements, which can inject into the parser using document.write(…). Due to the performance issues above, new features must not do this.

3.4. 具現化を阻む特能は避けること

~pageを具現化する前に資源の読込ngや他の演算を要求する特能は、 それまで~pageが空欄に（または以前の~pageのままに）なる結果， 利用者~体験が拙くなることが多い。 ◎ Features that require resource loading or other operations before rendering the page, often result in blank page (or the previous page). The result is a poor user experience.

そのような特能の追加を考慮するのは、 利用者~体験が総じて改善される事例に限ること。 これの正準的な例は、［ ~stylesheetを~downloadして処理するために具現化を阻む ］ことである — さもなければ、 未~styleな内容が明滅して，望ましくない利用者~体験になる。 ◎ Consider adding such features only in cases when the overall user experience is improved. A canonical example of this is blocking rendering in order to download and process a stylesheet. The alternative user experience is a flash of unstyled content, which is undesirable.

次も見よ ⇒＃ `§ 一部の~APIは専用~workerに限り公開するベキである＠#worker-only$ ◎ See also § 10.2.1 Some APIs should only be exposed to dedicated workers.

3.5. 内容~属性と~IDL属性の同期cを保つこと

新たな内容~属性には、［ 同じ名前を伴う対応する~IDL属性 ］があって，この 2 つの状態は同期するよう保たれるベキである。 同期される~IDL属性には一貫した名前を付けるベキである — さもないと作者を惑わすことになるので。 ◎ New content attributes should have a corresponding IDL attribute with the same name, and the state between the two should be kept synchronized. Carving out a synchronized IDL attribute with inconsistent naming results in confusion, and should be avoided.

注記： この逆も成立するわけではない。 新たな~IDL属性は、 常に ある内容~属性に相応するものを請合うとは限らない。 ◎ This does not hold the other way around. A new IDL attribute does not always warrant a content attribute counterpart.

3.6. ~URLを包含している属性は、首な目的に基づいて命名すること

新たな内容~属性は、［ 当の要素が，当の属性に包含される~URLへ~navigateすること ］を利用者に可能化する場合には， `href^a と命名すること — `a$e 要素の `href＠~HEmetadata#attr-link-href$a 属性の様に。 ◎ If the element enables the user to navigate to the URL contained in the attribute, call the attribute href, like the a element’s href attribute.

注記： 後の祭りだが、 `form$e の `action＠~HTMLforms#attr-fs-action$a 属性は， `href^a と命名されるベキであった。 ◎ Note: In hindsight, form's action attribute should have been named href.

所与の~URLにある資源を当の要素に読込ませる場合には、 当の属性を `src^a と命名すること — ［ `img$e 要素の `src＠~HEimages#attr-img-src$a 属性 ／ `script$e 要素の `src＠~HEscripting#attr-script-src$a 属性 ］の様に。 ◎ If the element causes the resource at the given URL to be loaded, call the attribute src, like the img element’s src attribute or the script element’s src attribute.

注記： ~HTMLには、 旧来の，模倣されるベキでない非~一貫性がいくつかある — 例えば， `link$e 要素の `href＠~HEmetadata#attr-link-href$a 属性は、 当の要素の `rel＠~HEmetadata#attr-link-rel$a 属性の値に依存して， ~naviを許容することも, 資源の読込ngを許容することもある。 ◎ Note: HTML has a number of legacy inconsistencies that should not be emulated, like the way link's href attribute might allow for navigation or for resource loading, depending on the value of the element’s rel attribute.

当の属性が識別する~URLが，当の要素の目的には補助的【！auxilliary】な場合、 当の属性を その意味論に従って命名すること — ［ `video$e の `poster＠~HEmedia#attr-video-poster$a ／ `q$e の `cite＠~HEtextlevel#attr-q-cite$a ／ `a$e の `ping＠~HTMLlinks#ping$a ］の様に。 ◎ If the attribute identifies a URL that is auxilliary to the element’s purpose, like video's poster, q's cite, or a’s ping, name the attribute after its semantics.

注記： ~URLを包含している属性は、 ~IDLにおいては `USVString$c として表現するベキであることにも留意すること — `§ 文字列を適切に表現すること＠#idl-string-types$を見よ。 ◎ Note: remember that attributes containing URLs should be represented in IDL as USVString; see § 8.2 Represent strings appropriately.

4.1. ~CSS~propは、何が別々に~cascadeされるべきかに基づいて分離すること

~CSS~propの値として，どれを一緒に~group化して どれを分離するべきかは、 何を独立に設定すればイミを成すかに基づいて裁定すること。 ◎ Decide which values should be grouped together as CSS properties and which should be separate properties based on what makes sense to set independently.

`~CSS~cascade法＠~CASCADE#cascading$【！~TR/2011/REC-CSS2-20110607/cascade.html#cascade】は、 ~CSS［ 規則／~stylesheet ］に属する`~CSS宣言＠~CSSOM1#css-declaration$【！~TR/2011/REC-CSS2-20110607/syndata.html#declaration】が別のそれを上書きすることを許容する。 一緒に上書きされるべき値たちが成す集合は、 一緒に~cascadeするよう，単独の~prop内に一緒に~group化されるべきである。 同様に，独立に上書き可能になるべき各~値は、 別々な~propに分けられるべきである。 ◎ CSS cascading allows declarations from different rules or different style sheets to override one another. A set of values that should all be overridden together should be grouped together in a single property so that they cascade together. Likewise, values that should be able to be overridden independently should be separate properties.

4.2. ~CSS~propが継承されるかどうかについて適切な選択を為すこと

ある~propが`継承-$されるべきかどうかは、 次に基づいて裁定すること ⇒ ~propによる効果は、 同じ~propが当の要素の ある先祖や子孫に設定された場合に［ 上書きされる／追加される ］どちらになるべきか。 ◎ Decide whether a property should be inherited based on whether the effect of the property should be overridden or added to if set on an ancestor as well as a descendant.

~propを要素に設定することによる効果が，要素の先祖に設定することによる効果 ⇒＃ を上書きする必要がある場合、当の~propは，おそらく継承されるべきである／ とは別々な効果を追加する場合、当の~propは，おそらく`継承されない^strongべきである ◎ If setting the property on a descendant element needs to override (rather than add to) the effect of setting it on an ancestor, then the property should probably be inherited. ◎ If setting the property on a descendant element is a separate effect that adds to setting it on an ancestor, then the property should probably not be inherited.

継承されない~propの仕様が，要素に対し［ 先祖の同じ~propの値を調べる取扱い ］を要求している場合（それは、遅くもなり得る）、［ 当の~propは，およそ継承されるべきであった ］ことを示唆する “~code臭（ `code smell^en, ~~兆候）” である。 継承される~propの仕様が，要素に対し［ ~propの値が要素の親の同じ~propの値と同じになる場合には，~propを無視する取扱い ］を要求している場合、［ 当の~propは，およそ継承されるべきでなかった ］ことを示唆する “~code臭” である。 ◎ A specification of an non-inherited property requiring that the handling of an element look at the value of that property on its ancestors (which may also be slow) is a "code smell" that suggests that the property likely should have been inherited. A specification of an inherited property requiring that the handling of an element ignore the value of a property if it’s the same as the value on the parent element is a "code smell" that suggests that the property likely should not have been inherited.

注記： ~textに対し効果がある~propは、 ほぼ常に［ 要素に設定することによる効果は、 要素の先祖に設定することによる効果を（追加するのではなく）上書きする必要がある ］ので，継承されるべきである。 これはまた、 次の設計~原則を保守するためにも必要になる ⇒ ~text片の周りに~styleを伴わない行内~要素を挿入しても 【`行内~box＠~CSSDISP#inline-box$を生成する要素で包装しても】， その~textの外観は変化しない。 ◎ If a property has an effect on text, then it’s almost always true that a descendant element needs to override (rather than add to) the effect of setting it on an ancestor, and the property should be inherited. This is also needed to maintain the design principle that inserting an unstyled inline element around a piece of text doesn’t change the appearance of that text.

4.3. 算出d値の型は、~propがどう継承されるべきかに基づいて選ぶこと

~CSS~propの`算出d値$は、［ 当の~propは、 値をどう`継承-$することになるか ］に基づいて選ぶこと — ［ 値が他の~propに依存する所では、 どう継承されるべきか ］も含めて。 ◎ Choose the computed value of a CSS property based on how it will inherit, including how values where it depends on other properties should inherit.

所与の~propの継承は、 次を意味する ⇒ 要素の［ 当の~prop ］の`算出d値$は、 要素の親の［ 当の~prop ］の`算出d値$から取得される — このことは、 次を意味する ⇒ 処理~手続きのうち，`算出d値$に到達するより ⇒＃ 前に起こるものは、`継承d値$に影響する／ 後に起こるもの（`使用~値$用のものなど）は、`継承d値$に影響しない ◎ Inheritance means that an element gets the same computed value for a property that its parent has. This means that processing steps that happen before reaching the computed value affect the value that is inherited, and those that happen after (such as for the used value) do not.

注記： `算出d値$と`解決d値$を混同するべきでない — 後者は、 `getComputedStyle()＠~CSSOM1#dom-window-getcomputedstyle$c ~methodが返す値である。 ◎ Note: the computed value should not be confused with the resolved value which is returned from the getComputedStyle() method.

<body style="font-size: 20px; line-height: 1.4">

  <p>
`body^e 内の この~textの行l高さは、
`28px^v になる。
◎
This body text has a line height of 28px.
</p>

  <h2 style="font-size: 200%">

`line-height^p は `body^e に宣言されているが、
この見出しの `line-height^p の使用~値は，
`28px^v ではなく `56px^v になる。
すなわち、
~font~sizeが `40px^v になろうが，行l高さを~overflowしない。
◎
This heading has a line-height of 56px, not 28px, even though the line-height was declared on the body. This means that the 40px font won’t overflow the line height.

  </h2>
</body>

次も見よ ⇒ `算出d値の~pattern＠https://wiki.csswg.org/spec/computed-values$ ◎ See also: • Computed Values Patterns

4.4. ~CSS~propとその値を適切に命名すること

~CSS~propの名前は，通例的に名詞であり、 それらの値の名前は，通例的に形容詞である（名詞のときもあるが）。 ◎ The names of CSS properties are usually nouns, and the names of their values are usually adjectives (although sometimes nouns).

［ ~prop／その値 ］を成す各~単語は、 ~hyphenで分離される。 一般に，略語は避けられる。 ◎ Words in properties and values are separated by hyphens. Abbreviations are generally avoided.

アリなときは単語の語根を利用すること — 文法~上の［ 接頭辞や接尾辞 ］を伴う形ではなく（例えば， `sizing^l ではなく `size^l ）。 ◎ Use the root form of words when possible rather than a form with a grammatical prefix or suffix (for example, "size" rather than "sizing").

~prop用の値たちが成す~listは、 一般に，新たな値を追加できるように選ぶべきである — 次に挙げる様な値は、 避けること ⇒ ［ `yes^v, `no^v, `true^v, `false^v ］, あるいは、 基本的にこれらと等価な，より複階的な名前を伴うもの ◎ The list of values of a property should generally be chosen so that new values can be added. Avoid values like yes, no, true, false, or things with more complex names that are basically equivalent to them.

~propの名前においては、［ "`mode^en"（~mode）, "`state^en"（状態） ］の様な単語は避けること — ~propは、 一般に［ ~mode／状態 ］を設定するものなので。 ◎ Avoid words like "mode" or "state" in the names of properties, since properties are generally setting a mode or state.

命名に対する一般的な（各種~言語にわたる）助言は、 `§ 命名~原則＠#naming-is-hard$ を見よ。 ◎ See § 12 Naming principles for general (cross-language) advice on naming.

4.5. 内容は既定で~view可能かつ~access可能になるべきである

~CSS~prop, および~CSS~layout~systemは （それらは概して， `display$p ~propの値【で指定される】）、 次を保全するように設計すること ⇒ 内容は、 既定では［ ~view可能, ~access可能, 利用-可能 ］になる ◎ Design CSS properties or CSS layout systems (which are typically values of the display property), to preserve the content as viewable, accessible and usable by default.

5.1. ~Web~APIには~JSを利用すること

~Web用に命令的な~APIを設計するときは、 ~JSを利用すること。 特に、 【多数の言語に】一般~化する必要はなく，【~JS】言語に特有な［ 意味論／規約 ］に自由に依拠できる。 ◎ When designing imperative APIs for the Web, use JavaScript. In particular, you can freely rely upon language-specific semantics and conventions, with no need to keep things generalized.

注記： ~JSは、 名前 `ECMASCRIPT$r の下で標準~化されている。 ◎ JavaScript is standardized under the name [ECMASCRIPT].

注記： `WEBIDL$r は，別々な “§ ~ES言語束縛” を定義するが、 それは［ ~Web~IDLは、 他の~programming言語における言語束縛も備えることを意図する ］ことは含意しない。 ◎ [WEBIDL] defines a separate "ECMAScript binding" section, but this doesn’t imply that Web IDL is intended to have bindings in other programming languages.

5.2. 完了まで走る（ `run-to-completion^en ）意味論を保全すること

~JS`~event~loop$が走っている間は、 ~JS~APIを介して~accessされた~dataを改変しないこと。 ◎ Don’t modify data accessed via JavaScript APIs while a JavaScript event loop is running.

~JS~Web~APIは、 一般に， C++ や Rust などの低~levelな言語にて実装された特能を包装するものである。 それらの言語と違って，~JSを利用しているときは、 開発者は［ ある~code片が実行し始めたなら，完了するまで実行し続けることになる ］ものと期待できる。 ◎ A JavaScript Web API is generally a wrapper around a feature implemented in a lower-level language, such as C++ or Rust. Unlike those languages, when using JavaScript developers can expect that once a piece of code begins executing, it will continue executing until it has completed.

そのため、 ~JS作者は次を当然のことと~~見なす ⇒ ある関数にて可用にされた~dataは、 当の関数が走っている間に予期せず変化することはない。 ◎ Because of that, JavaScript authors take for granted that the data available to a function won’t change unexpectedly while the function is running.

なので、 ある~JS~Web~APIが，何らかの~data片（~obj~propなど）を公開する場合、 ~UAは，~JS~taskが走っている間は その~dataを更新してはナラナイ。 下層の~dataが変化した場合には、 代わりに，［ 当の~dataの公開される~versionを改変する ］ための`~taskを~queueする$こと。 ◎ So if a JavaScript Web API exposes some piece of data, such as an object property, the user agent must not update that data while a JavaScript task is running. Instead, if the underlying data changes, queue a task to modify the exposed version of the data.

5.3. ~garbage収集を公開しないこと

当の~JS~Web~APIは、 次を確保すること ⇒ ~garbage収集の時機を知る仕方を作者に供さない ◎ Ensure your JavaScript Web APIs don’t provide a way for an author to know the timing of garbage collection.

~garbage収集の時機は，~UAごとに異なることに加え、 ~UAが処理能を改善する作業に伴い，時を経て変化することもある。 ある~APIが~garbage収集の時機を公開した場合、 ~programの挙動が文脈に応じて異なる原因になり得る。 これは、 作者が これらの相違点を取扱うために加的な~codeを書する必要があることを意味する。 また，時機に依存するような特定0の仕方で働く~codeが~~普及すると、 ~UAは異なる~garbage収集~策を実装するのが困難になり得る。 ◎ The timing of garbage collection is different in different user agents, and may change over time as user agents work on improving performance. If an API exposes the timing of garbage collection, it can cause programs to behave differently in different contexts. This means that authors need to write extra code to handle these differences. It may also make it more difficult for user agents to implement different garbage collection strategies, if there is enough code which depends on timing working a particular way.

このことは、 弱い参照として動作する~API — 例： ~garbage収集が走ったなら ~NULL になるような~prop — は，公開するべきでないことを意味する。 ~JS~codeにおける［ ~obj／~data ］の存続期間は予測-可能になるべきである。 ◎ This means that you shouldn’t expose any API that acts as a weak reference, e.g. with a property that becomes null once garbage collection runs. Object and data lifetimes in JavaScript code should be predictable.

`getElementsByTagName()$c は、 ~garbage収集の時機に依存し得ることについて何も告げない。 対照的に［ `WeakRef$jT ／ `FinalizationRegistry$jT ］の様な，~garbage収集に依存するよう明示的に設計された~APIは、［ ~garbage収集との相互作用についての作者の期待 ］に正確aに沿うよう設定されている。 ◎ getElementsByTagName gives no sign that it may depend on the timing of garbage collection. In contrast, APIs which are explicitly designed to depend on garbage collection, like WeakRef or FinalizationRegistry, set accurate author expectations about the interaction with garbage collection.

6.1. 属性は~data~propの様に挙動するべきである

~IDL属性 `WEBIDL$r は、 単純な~JS~obj~propの様に動作するべきである。 ◎ [WEBIDL] attributes should act like simple JavaScript object properties.

現実においては、 ~IDL属性は，別々な［ 取得子, 設定子 ］~methodを伴う，~accessor~propとして実装される。 それらが~JS~obj~prop様に動作するためには： ◎ In reality, IDL attributes are implemented as accessor properties with separate getter and setter methods. To make them act like JavaScript object properties:

• 取得子は、 観測-可能な副作用を伴ってはナラナイ。 ◎ Getters must not have any observable side effects.
• 取得子は、 複階的な演算を遂行するべきでない。 ◎ Getters should not perform any complex operations.
• `obj.attribute === obj.attribute^c が常に ~T になることを確保すること。 取得子が~callされる回ごとに新たな値を作成しないこと。 ◎ Ensure that obj.attribute === obj.attribute is always true. Don’t create a new value each time the getter is called.
• アリなら、 obj.attribute = %x に~~後続する obj.attribute === %x は， ~T に評価されることを確保すること。 （ %x に対し何らかの種類の変換が必要yな場合、 これはアリでないこともある。） ◎ If possible, ensure that given obj.attribute = x, obj.attribute === x is true. (This may not be possible if some kind of conversion is necessary for x.)

ある属性を利用していて，この仕方で挙動しないことについて考している場合、 おそらく，代わりに~methodを利用するべきである。 ◎ If you were thinking about using an attribute, but it doesn’t behave this way, you should probably use a method instead.

6.2. ~objは~liveか静的どちらになるべきか考慮すること

~APIが何らかの内部~状態を表現している~objへの~accessを与える場合、［ 当の~objは，当の状態が変化するに伴い更新され続けるべきである ］かどうかを裁定すること。 ◎ If an API gives access to an object representing some internal state, decide whether that object should continue to be updated as the state changes.

~objのうち，いつの時点でも現在の状態を表現するものは `~live~obj@ である一方、 作成された時点の状態を表現するものは `静的~obj@ である。 ◎ An object which represents the current state at all times is a live object, while an object which represents the state at the time it was created is a static object.

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;

    /* 
これには %list から `td^e 除去する副作用があり、
反復を予測-不能にする。
◎
This has the side-effect of removing td from the list, causing the iteration to become unpredictable.
 */
    %td.parentNode.replaceChild(%tr, %td);
}

6.3. 属性か~methodか適切な方を利用すること

ときには、［ 属性, ~method ］どちらを利用するか明瞭でないこともある。 ◎ Sometimes it is unclear whether to use an attribute or a method.

• 属性~取得子は、 （観測-可能な）副作用を伴ってはナラナイ。 副作用が予期される場合、 ~methodを利用すること。 ◎ Attribute getters must not have any (observable) side effects. If you have expected side effects, use a method.

• 属性~取得子は、 例外を投出するベキでない： ◎ Attribute getters should not throw exceptions.＼

  • 取得子は，`~data~propの様に挙動するべき＠#attributes-like-data$であり、 定例の~data~propが読取られるときは，例外を投出するべきでない。 ◎ Getters should behave like regular data properties, and regular data properties do not throw exceptions when read.＼
  • 妥当でない状態は、 一般に~dataの書込nを却下することにより，避けるベキである — `読取られる^emときではなく。 ◎ Furthermore, invalid state should generally be avoided by rejecting writes, not when data is read.＼
  • 既存の取得子を例外を投出するよう更新することは、 避けるベキである。 既存の~APIの利用者は、 当の~API【の各~取得子の結果】を［ 列挙する／包装する ］こともあり，新たな例外を予期しないので、 そうすると，後方-互換性を非互換化することになる。 ◎ Updating existing getters to throw exceptions should be avoided as existing API users may enumerate or wrap the API and not expect the new exception, breaking backwards compatibility.
• 属性~取得子は、 他を阻む演算を遂行するベキでない。 ある取得子が，他を阻む演算を遂行することを要求する場合、 ~methodにするベキである。 ◎ Attribute getters should not perform any blocking operations. If a getter requires performing a blocking operation, it should be a method.
• 属性~取得子は、 下層の~objが変化するまでの間は， ~callされる回ごとに同じ~objを返すべきである。 すなわち、 常に `obj.attribute === obj.attribute^c が満たされなければならない。 属性~取得子から毎回~新たな値を返すのは許容されない。 これを満たせない取得子は、 ~methodにするべきである。 ◎ If the underlying object has not changed, attribute getters should return the same object each time it is called. This means obj.attribute === obj.attribute must always hold. Returning a new value from an attribute getter each time is not allowed. If this does not hold, the getter should be a method.

注記： 他を阻む演算を伴う~antipatternの例は、 `offsetTop＠~CSSOMVIEW#dom-htmlelement-offsettop$c の様な~layoutを遂行する取得子である。 ◎ Note: An antipattern example of a blocking operation is with getters like offsetTop performing layout.

属性は，アリなときは、 その設定子に与えられた値を取得子から返すために保全すること。 すなわち、 obj.attribute = %x に~~後続する obj.attribute === %x は， ~T に評価されるべきである （このことは — 例えば，正規化や型~変換の段が必要yな場合など — 常に該当するとは限らないが、 通常の~code~path用には， 目標として保持されるべきである。） ◎ For attributes, whenever possible, preserve values given to the setter for return from the getter. That is, given obj.attribute = x, a subsequent obj.attribute === x should be true. (This will not always be the case, e.g., if a normalization or type conversion step is necessary, but should be held as a goal for normal code paths.)

`~liveな~obj, 静的な~obj＠#live-vs-static$ どちらを返すことも求まれ得る。 このことは、 次を意味する： ◎ The object you want to return may be live or static. This means:

• ~liveである場合、 毎回~同じ~objを返すこと — ある状態~変化により，異なる~objを返すよう要求されるまでは。 属性, ~methodどちらも，これを返し得る。 ◎ If live, then return the same object each time, until a state change requires a different object to be returned. This can be returned from either an attribute or a method.
• 静的な場合、 毎回~新たな~objを返すこと。 この事例は、 ~methodに限られるべきである。 ◎ If static, then return a new object each time. In which case, this should be be a method.

6.4. 省略可能な／~primitiveな引数は辞書を通して受容すること

~API~methodは、 一般に，一連の省略可能な引数の代わりに`辞書$引数を利用するべきである。 ◎ API methods should generally use dictionary arguments instead of a series of optional arguments.

そうすれば、 当の~methodを~callする~codeは より可読になり， ~methodの~signatureも覚え易くなる。 また、 将来に当の~APIを より拡張-可能にする — 特に，同じ型を伴う複数個の引数が必要になる場合に。 ◎ This makes the code that calls the method more readable, and the method signature easier to remember. It also makes the API more extensible in the future, particularly if multiple arguments with the same type are needed.

new Event("example", { bubbles: true, cancelable: false})

new Event("example", true, false)

義務的な~parameterを辞書を通して受容することも — そうした方が，当の~APIが可読になるなら — 考慮するベキである — とりわけ、 それらが~primitive型であるときは。 ◎ You should also consider accepting mandatory parameters through a dictionary, if it would make the API more readable, especially when they are of primitive types.

window.scrollBy({ left: 50, top: 0 })

window.scrollBy(50, 0)

当の`辞書$自身は、 省略可能な引数にするべきである — 作者が すべて既定の~optionで~~満足な場合、 余分な引数を渡さなくとも済むよう。 ◎ The dictionary itself should be an optional argument, so that if the author is happy with all of the default options, they can avoid passing an extra argument.

%element.scrollIntoView(false, {});

%element.scrollIntoView(false);

次も見よ ⇒＃ `Hall of API Shame:Boolean Trap＠https://ariya.io/2011/08/hall-of-api-shame-boolean-trap$en（ “真偽値の罠” ）／ `真偽値~引数が既定で ~T になる~API＠https://lists.w3.org/Archives/Public/public-script-coord/2013OctDec/0302.html$ `§ ~methodの引数は、アリなら省略可能にすること＠#optional-parameters$／ `§ 省略可能な引数を適切に命名すること＠#naming-optional-parameters$／ ◎ See also: • Hall of API Shame: Boolean Trap. • APIs that have boolean arguments defaulting to true • § 6.5 Make method arguments optional if possible • § 6.6 Name optional arguments appropriately

6.5. ~methodの引数は、アリなら省略可能にすること

~API~method用の ある引数に適理な既定の値がある場合、 その引数を省略可能にして，既定の値を指定すること。 ◎ If an argument for an API method has a reasonable default value, make that argument optional and specify the default value.

注記： 旧来の相互運用能の理由から，これには例外もあるが（ `XMLHttpRequest$I など）、 それは推奨される実施ではなく，設計の過ちと見なされるべきである。 ◎ Note: Exceptions have been made for legacy interoperability reasons (such as XMLHttpRequest), but this should be considered a design mistake rather than recommended practice.

~APIは、［ 引数が~~省略された場合に利用される既定の値は、 `undefined$c を当の引数の型に変換した結果と同じになる ］ように設計されなければナラナイ。 例えば，真偽値~引数が設定されない場合の既定は ~F でなければナラナイ。 ◎ The API must be designed so that if an argument is left out, the default value used is the same as converting undefined to the type of the argument. For example, if a boolean argument isn’t set, it must default to false.

当の~APIに用いる~list~data型を裁定するときは、 他が要求されない限り，次に挙げる~list型を利用すること： ◎ When deciding between different list data types for your API, unless otherwise required, use the following list types:

• ~methodの~list引数は、 `連列~型$になるべきである。 ◎ Method list arguments should be of type sequence<T>
• ~methodの返り値は、 `連列~型$になるべきである。 ◎ Method return values should be of type sequence<T>
• 属性は、 `観測-可能な配列~型$になるべきである。 ◎ Attributes should be of type ObservableArray<T>

次も見よ ⇒ `§ 省略可能な／~primitiveな引数は辞書を通して受容すること＠#prefer-dictionaries$ ◎ See also: • § 6.4 Accept optional and/or primitive arguments through dictionaries

6.6. 省略可能な引数を適切に命名すること

省略可能な引数は、 否定的な名前にしないで，既定の挙動が明白になるよう命名すること。 ◎ Name optional arguments to make the default behavior obvious without being named negatively.

これは、 `辞書~内に供される＠#prefer-dictionaries$ときも, `単独の引数として供される＠#optional-parameters$ときも適用される。 ◎ This applies whether they are provided in a dictionary or as single arguments.

次も見よ ⇒ `§ 命名~原則＠#naming-is-hard$ ◎ See also: • § 12 Naming principles

6.7. 多重定義を賢く利用すること

ある~methodの挙動が，渡された引数に依存して有意に異なることになる場合、 通例的には，別々な~methodを定義するベキである — 単独の~methodを`多重定義-$するのでなく。 ◎ If the behaviour of a method will be significantly different depending on the arguments passed you should usually define a separate method rather than overload a single method.

~methodの多重定義は、 いずれかの引数が［ 1 個の値, 値たちが成す配列 ］どちらもとり得るときなどに有用になる。 類似に，~optionたちが成す辞書を渡すことは、 より柔軟性を許容するので，良い~patternである。 ◎ Overloading a method such that one of its arguments can be either a single value or an array of values is useful. Similarly, passing a dictionary of options is a good pattern because it allows for more flexibility.

しかしながら，ある~methodにおいて［ 渡された最初の引数に応じて後続な引数を変更する必要がある場合 ］や［ 各~入力の型に依存して挙動が異なる場合 ］には、 多重定義を避けるベキである — ~codeの可読性を邪魔して， 作者が~APIの機能性を発見するのが困難になり得るので。 ◎ However, if subsequent arguments for a method have to change because of the first argument passed, or if a method has different behaviour depending on the types of inputs, this can hinder code readability, and make discovering API functionality more difficult for authors, and should be avoided.

6.8. ~classは、アリなときは，構築子を備えるべきである

当の~APIの一部を成す~classは、 適切になるなら，構築子を備えるようにすること。 ◎ Make sure that any class that’s part of your API has a constructor, if appropriate.

`WEBIDL$r ~interfaceは，既定では “構築-可能でない” ~classを生成するので、 それらの~instanceを `new X()^c を利用して作成しようと試行すると， `TypeError$E を投出することになる。 それらは、 次により構築-可能にできる ⇒ 当の~interfaceに適切な`構築子~演算$を追加して， 当の~classの新たな~instanceを作成する~algoを定義する ◎ By default, [WEBIDL] interfaces generate "non-constructible" classes: trying to create instances of them using new X() will throw a TypeError. To make them constructible, you can add appropriate constructor operations to your interface, and defining the algorithm for creating new instances of your class.

これは、［［ 当の~classの~instanceを受容する第三者-主体~library ］とともに［ ~testする／模擬する／~interfaceする ］などの目的で，~classの~instanceを作成すること ］を，~JS開発者に許容する。 それは、 当の~classの下位classを作成する能も作者に与える — 無い場合、 そのような能は，~JSが下位classを取扱う仕方により防止される。 ◎ This allows JavaScript developers to create instances of the class for purposes such as testing, mocking, or interfacing with third-party libraries which accept instances of that class. It also gives authors the ability to create a subclass of the class, which is otherwise prevented, because of the way JavaScript handles subclasses.

これが適切にならない事例もある — 例えば： ◎ This won’t be appropriate in all cases. For example:

• 一部の~objは，特権的な資源への~accessを表現するので、 そのような資源へ~accessできる~factory~methodにより構築される必要がある。 ◎ Some objects represent access to privileged resources, so they need to be constructed by factory methods which can access those resources.
• 一部の~objは，その~lifecycleがとても注意深く制御されるので、 特定の~methodを通して作成され, ~accessされる必要がある。 ◎ Some objects have very carefully controlled lifecycles, so they need to be created and accessed through specific methods.
• 一部の~objは，抽象-基底~classを表現するので、 構築されるべきでなく，作者は それ用の下位classを定義-可能になるべきでない。 ◎ Some objects represent an abstract base class, which shouldn’t be constructed, and which authors should not be able to define subclasses for.

~factory~methodは，構築子を補うものになり得るが、 一般に，構築子の`代わり^emとして利用されるべきでない。 それでも，構築子に加えて~factory~methodを含めることは、 追加的な便益を供するなら価値をもたらし得る。 そのような共通的な事例は、 ~APIが ある基底~class, 複数個の特化された下位classを含んでいて，［ 渡された~parameterに基づいて適切な下位classを作成する ］ための~factory~methodを伴うときである。 ~factory~methodは、［ 返される結果に共通かつ最も近い基底~下位class ］上の静的~methodになることが多い。 ◎ Factory methods can complement constructors, but generally should not be used instead of them. It may still be valuable to include factory methods in addition to constructors, when they provide additional benefits. A common such case is when an API includes base classes and multiple specialized subclasses, with a factory method for creating the appropriate subclass based on the parameters passed. Often the factory method is a static method on the closest common base subclass of the returned result.

6.9. 適切なときは同期的にすること

新たな~APIを設計するときは、 アリな所では，同期的な~APIを選好すること。 同期的な~APIを利用する方が単純であり、 設定しておく必要な基盤（関数を `async^c にするなど）も少なくなる。 ◎ Where possible, prefer synchronous APIs when designing a new API. Synchronous APIs are simpler to use, and need less infrastructure set-up (such as making functions async).

一般に~APIは、 次に挙げる~~経験則が適用される場合には，同期的にするべきである： ◎ An API should generally be synchronous if the following rules of thumb apply:

• ~APIは、 許可~promptや装置~選定器などの~dialogの背後で通過制御されるものと期待されてはいない。 ◎ The API is not expected to ever be gated behind a permission prompt, or another dialog such as a device selector.
• ~APIの実装は、［ ~lock／~filesystem／~network~access ］ — 例えば，~process間の通信 — により阻止されない。 ◎ The API implementation will not be blocked by a lock, filesystem or network access, for example, inter-process communication.
• 実行~時間は、 短くかつ決定的である。 ◎ The execution time is short and deterministic.

6.10. 非同期的な~APIは~Promiseを利用して設計すること

~API~methodを非同期的にする必要がある場合、 ~callback関数ではなく，~Promiseを利用すること。 ◎ If an API method needs to be asynchronous, use Promises, not callback functions.

~web~platform~~全般に一貫して~Promiseを利用することは、 ~promiseを連鎖するなど，~APIを他と一緒に利用するのも より容易になることを意味する。 また，~promiseを利用している~codeの方が、 ~callback関数を利用している~codeより容易に理解できる傾向にある。 ◎ Using Promises consistently across the web platform means that APIs are easier to use together, such as by chaining promises. Promise-using code also tends to be easier to understand than code using callback functions.

次のいずれかに該当する場合、 ~APIは非同期的にする必要があるかもしれない： ◎ An API might need to be asynchronous if:

• ~UAは利用者に `許可＠#consent$ を~promptする必要があるとき。 ◎ the user agent needs to prompt the user for permission,
• 何らかの情報を［ ~diskから読取る／~networkへ要請する ］必要があるかもしれないとき。 ◎ some information might need to be read from disk, or requested from the network,
• ~UAは、 結果を返す前に別の［ ~thread上で／~process内で ］有意な量の作業を行う必要もあるとき。 ◎ the user agent may need to do a significant amount of work on another thread, or in another process, before returning the result.

次も見よ ⇒ `~Promiseを利用する仕様の書法＠~PROMISES$ ◎ See also: • Writing Promise-Using Specifications

6.11. 非同期的な~APIや演算を取消すときは `AbortSignal^I を利用すること

非同期的な~methodが取消され得る場合、［ ~option群を成す`辞書$の一部として `AbortSignal$I を渡す ］ことを作者に許容すること。 ◎ If an asynchronous method can be cancelled, allow authors to pass in an AbortSignal as part of an options dictionary.

const %controller = new AbortController();
const %signal = %controller.signal;
geolocation.read({ %signal });

非同期的な演算を取消す仕方として， `AbortSignal^I を一貫して利用すれば、 作者は，~codeをもっと単純に書せるようになる。 ◎ Using AbortSignal consistently as the way to cancel an asychronous operation means that authors can write less complex code.

例えば，次のような~patternがある ⇒ 同じ `AbortSignal^I を何個かの進行中な演算に利用した上で，必要yな場合は （利用者から取消すよう要請されたときや，単-~page~appにおいて~naviが生じたときなど）、 対応する `AbortController$I を利用して，すべての演算を まとめて取消すなど。 ◎ For example, there’s a pattern of using a single AbortSignal for several ongoing operations, and then using the corresponding AbortController to cancel all of the operations at once if necessary (such as if the user presses "cancel", or a single-page app navigation occurs.)

`AbortController$I は、 取消nが保証できない場合でも利用できる — その `abort()＠~DOM4#dom-abortcontroller-abort$c ~methodの~callは、 保証ではなく要請なので。 ◎ Even if cancellation can’t be guaranteed, you can still use an AbortController, because a call to abort() on AbortController is a request, rather than a guarantee.

6.12. 定数や列挙d値には文字列を利用すること

当の~APIに［ 定数／列挙d値たちが成す集合 ］が必要な場合、 文字列~値を利用すること。 ◎ If your API needs a constant, or a set of enumerated values, use string values.

文字列の方が開発者にとって検分するのが容易であり、 ~JS~engineにおいても，文字列に代えて整数を利用することで得られる処理能の便益は無い。 ◎ Strings are easier for developers to inspect, and in JavaScript engines there is no performance benefit from using integers instead of strings.

状態を~propの組合nで表出する必要がある場合、 代わりに辞書~objを利用すること — 別の言語では、 ~bitmaskとして表出されることもあろうが。 この~objは、 単独の~bitmask値と同じくらい容易に受け渡せる。 ◎ If you need to express a state which is a combination of properties, which might be expressed as a bitmask in another language, use a dictionary object instead. This object can be passed around as easily as a single bitmask value.

6.13. 非同期的, 同期的どちらの~methodも必要な場合、同期的な方を例外とすること

稀な事例では、 同じ目的に［ 同期的, 非同期的 ］どちらの~methodも必要になる — その場合、 非同期的な方を既定として，同期的な方は例外とすること。 ◎ In the rare case where you need to have both synchronous and asynchronous methods for the same purpose, default to asynchronous and make synchronous the exception.

~web~platformの一部を成す特定の分野は、 現在の制限に因り，非同期的な~supportを欠いている。 したがって、［ 非同期的な~methodに加えて，同期的な~method用の~supportを備える ］ことは，利便性に有益になり得る。 これらの事例は例外であり、 同期的な~methodは，~web~platformの能力が発展するに伴って非推奨にされる明瞭な道があると見なすこと。 ◎ Due to current limitations, some specific areas of the web platform lack asynchronous support. Therefore having support for synchronous methods in addition to asynchronous methods can be beneficial for usability. Consider these cases an exception, and have a clear path for deprecation of the synchronous methods as web platform capabilities evolve.

ほとんどの事例では、 同期的な変種は， `Sync()^c 接尾辞を伴うよう命名することにより判別されるベキである。 ◎ For most cases, the synchronous variant should be distinguished by naming it with a Sync() suffix.

注記： 現時点で，これが適用-可能な周知な事例として， ~JSと~WASMの境界をまたぐ設計が挙げられる — 現今では、 `Promise integration＠https://github.com/WebAssembly/js-promise-integration/blob/main/proposals/js-promise-integration/Overview.md$cite （~promiseの統合）は，依然として開発~下にあるので。 ◎ At the moment, one well-known case where this is applicable is when a design has to cross boundaries between JavaScript and WASM, as the Promise integration is still under development as of today.

6.14. ~byteたちが成す配列は `Uint8Array^c で出力すること

~APIが~byte配列を返す場合、 それを `ArrayBuffer$c ではなく `Uint8Array$c にすること。 ◎ If an API returns a byte array, make it a Uint8Array, not an ArrayBuffer.

`ArrayBuffer^c からは直に読取れないので、 開発者は，~dataを読取るために `Uint8Array^c などの~viewを作成する必要がある。 `Uint8Array^c を供すれば，そのような追加的な労は避けられる。 ◎ ArrayBuffers cannot be read from directly; the developer would have to create a view such as a Uint8Array to read data. Providing a Uint8Array avoids that additional effort.

~buffer内の~byte列には，他の いずれかの`有型~配列~型$【！ `TypedArray^jT 型】として自然な解釈【！intepretation】がある場合、 代わりに，それを供すること。 例えば，~byte列が `float$c【！`Float32^c】 値たちを表現する場合、 `Float32Array$c を利用すること。 ◎ If the bytes in the buffer have a natural intepretation as one of the other TypedArray types, provide that instead. For example, if the bytes represent Float32 values, use a Float32Array.

7.1. 一度限りの~event用には~promiseを利用すること

`~promiseを利用している仕様の書法＠~PROMISES$ 指針における`助言＠~PROMISES#one-time-events$に従うこと。 ◎ Follow the advice in the Writing Promise-Using Specifications guideline.

7.2. ~eventは関係する~promiseを解決する前に発火するべきである

~Promiseに基づく非同期的な~algoが ある~event %~event を配送する場合、 当の~Promise %~promise を解決した後ではなく，解決する前に配送するべきである： ◎ If a Promise-based asynchronous algorithm dispatches events, it should dispatch them before the Promise resolves, rather than after.

%~promise が解決されるときは、 その反応~callback %~callback を走らすための`小task$ %小task が~queueされる。 %小task は、 ~JS~stackを空にするとき処理される。 `~eventの配送-法＠~DOM4#dispatching-events$は、 同期的であり，各~listener【に対する~call】の合間に~JS~stackを空にすることを孕む。 よって、 %~event を配送する前に %~promise を解決した場合， %小task は %~event 用の 1 個目の~listenerと 2 個目の~listenerの合間に呼出されることになる。 ◎ When a promise is resolved, a microtask is queued to run its reaction callbacks. Microtasks are processed when the JavaScript stack empties. Dispatching an event is synchronous, which involves the JavaScript stack emptying between each listener. As a result, if a promise is resolved before dispatching a related event, any microtasks that are scheduled in reaction to a promise will be invoked between the first and second listeners of the event.

初めに %~event を配送するようにしておけば、 %小task が そのように差挟まれることは防止され， すべての~event~listenerは， %~callback より前に呼出されるようになる。 ◎ Dispatching the event first prevents this interleaving. All event listeners are then invoked before any promise reaction callbacks.

7.3. 自前の~event~listenerの様な基盤を考案しないこと

通知を生成することで，ある処理nを［ 開始する／停止する ］ことを作者に許容する~APIを作成しているときは、 既存の~event基盤を利用して，通知を~listenするのを許容すること。 下層の処理nを［ 開始する／停止する ］ための制御~用には、 別々な~APIを作成すること。 ◎ When creating an API which allows authors to start and stop a process which generates notifications, use the existing event infrastructure to allow listening for the notifications. Create separate API controls to start/stop the underlying process.

次も見よ ⇒＃ `§ 通知~用には~eventを利用すること＠#events-are-for-notification$／ `§ ~eventか観測器か適切な方を利用すること＠#events-vs-observers$／ § 状態~用には素な `Event^I を利用すること ◎ See: • § 7.5 Use events for notification • § 7.8 Use Events and Observers appropriately • § 7.7 Use plain Events for state

7.4. 常に~event~handler属性を追加すること

当の~APIが新たな~event型を追加する場合、 それを取扱うであろう各 `EventHandler$I の~interfaceにも， 対応する`~event~handler~IDL属性$を — 当の~event型が `foo^et ならば `onfoo^c を — 追加すること。 ◎ If your API adds a new event type, add a corresponding onyourevent event handler IDL attribute to the interface of any EventHandler which may handle the new event.

~event~handler~IDL属性を定義し続けることは、 次に挙げることから重要になる： ◎ it’s important to continue to define event handler IDL attributes because:

• ~platformにおける一貫性を保全する。 ◎ they preserve consistency in the platform
• ~supportされる~event用の特能~検出を可能化する （`§ 新たな特能は検出-可能になるべきである＠#feature-detect$ を見よ）。 ◎ they enable feature-detection for the supported events (see § 2.5 New features should be detectable)

注記： 一貫性を得るため、 当の~eventが［ ~HTML／~SVG ］要素により取扱われる必要がある場合には， 当の`~event~handler~IDL属性$を `GlobalEventHandlers$I ~interface~mixinに追加すること — 関連な要素~interface（たち）に直に追加するのではなく。 類似に， `Window$I により取扱われる必要がある場合には， 当の`~event~handler~IDL属性$を `WindowEventHandlers$I に追加すること。 ◎ For consistency, if the event needs to be handled by HTML and SVG elements, add the event handler IDL attributes on the GlobalEventHandlers interface mixin, instead of directly on the relevant element interface(s). Similarly, add event handler IDL attributes to WindowEventHandlers rather than Window.

7.5. 通知~用には~eventを利用すること

~eventは、 変更を誘発するために利用されるべきでない。 ~eventは、［ 変化が起きたことは，すでに完遂したこと ］の通知を送達するために限られる。 ◎ Events shouldn’t be used to trigger changes, only to deliver a notification that a change has already finished happening.

7.6. 再帰の能性に抗して防護すること

当の~APIが［ 長く走る／複雑な ］~algoを含む場合、 それが走っている間は，当の~algoの中へ~callするのを防止すること。 ◎ If your API includes a long-running or complicated algorithm, prevent calling into the algorithm if it’s already running.

ある~API~methodが，長く走る~algoを始める原因になる場合、 `通知~用の~event＠#events-are-for-notification$を利用して， 当の~algoの進捗を利用元~codeに通知するべきである。 しかしながら、 当の~eventを取扱う利用元~codeは，同じ~API~methodを~callし得るので、 複階的な~algoを再帰的に走らす原因になる — それは、 同じ~eventを再び発火し得るので，同じ~event~handlerを発火する原因になり, 以下同様に続く。 ◎ If an API method causes a long-running algorithm to begin, you should use events to notify user code of the progress of the algorithm. However, the user code which handles the event may call the same API method, causing the complex algorithm to run recursively. The same event may be fired again, causing the same event handler to be fired, and so on.

これを防止するため、 当の~API~methodの中への “再帰的な” ~callは， 単純に即時に【すなわち，何もせずに】返るようにすること。 この技法は、 ~algoの “防護-法（ `guarding^en ）” と称される。 ◎ To prevent this, make sure that any "recursive" call into the API method simply returns immediately. This technique is "guarding" the algorithm.

この仕方で常に “防護-可能” になるとは限らない。 例えば，ある~algoは、 それらすべてを依拠-可能に検査するには，入口【すなわち，当の~algoを呼出している箇所】が多過ぎることもある。 これに該当する事例における別の~optionは、 作者~codeを~callするのを［ `~task$／`小task$ ］へ先送りすることである。 これは，再帰の~stackを避けるが、 後続して~queueされる~taskたちにより際限ない~loopが生じる~riskは避けれない。 ◎ You won’t always be able to "guard" in this way. For example, an algorithm may have too many entry-points to reliably check all of them. If that’s the case, another option is to defer calling the author code to a later task or microtask. This avoids a stack of recursion, but can’t avoid the risk of an endless loop of follow-up tasks.

~eventを先送りするときは、 “… `~eventを発火する$ための`~taskを~queueする$ …” として指定されることが多い。 ◎ Deferring an event is often specified as "queue a task to fire an event...".

~eventは、 それを誘発する~algoが異なる［ ~thread／~process ］上で走ることもある場合には，常に先送りするべきである。 この事例で先送りすることは、［ 当の~eventが`~task~queue$内の正しい`~task$で処理できる ］ことを確保する。 ◎ You should always defer events if the algorithm that triggers the event could be running on a different thread or process. In this case, deferral ensures the events can be processed on the correct task in the task queue.

［ “防護-法”, “先送り法” ］どちらの~approachにも，~trade-offがある： ◎ Both the "guarding" and the "deferring" approach have trade-offs.

~algoの “防護-法” は次を保証する： ◎ "Guarding" an algorithm guarantees:

• ［ 防護された~algoの終了~時から，~eventが発火される時点まで ］の間，状態が変化し得る機会cは無い。 ◎ at the time events are fired, there is no chance that the state may have changed between the guarded algorithm ending and the event firing.
• ~algoの間に発火された~event — 当の~algoの一部として為された状態~変更を利用元~codeに通知する~eventなど — は、 次回の`~task$まで待機する必要なく，即時に発火でき、 当の変化を~codeに通知することになる。 ◎ events fired during the algorithm, such as events to notify user code of a state change made as part of the algorithm, can be fired immediately, notifying code of the change without needing to wait for the next task.
• ~event~handler内で走っている利用元~codeは、 その発火-先の~instance~obj上で，関連な状態を直に観測できる — 当の~eventに関連な状態の複製を【利用元~codeに】与える必要はない。 ◎ user code running in the event handler can observe relevant state directly on the instance object they were fired on, rather than needing to be given a copy of the relevant state with the event.

当の~eventが代わりに先送りされた場合： ◎ If the events are deferred instead:

• 当の~algoが完了した時点で，それ【~eventを発火する~task】が`~task~queue$内で最初の`~task$になる保証は無い。 ◎ there is no guarantee that they will be first in the task queue once the algorithm completes.

• 当の~objの状態を変更し得る他の`~task$は、 先送りされた~eventに当の~eventに関連な状態がある場合には，それを伴うよう含めるべきである。 ◎ any other task may change the object’s state you should include any state relevant to the event with the deferred event.

  注記：【！class="informative】 これは通例的に、 状態を保持するための新たな属性を伴う，新たな［ `Event$I の下位class ］を孕む。 例えば， `ProgressEvent$I は、 状態を保持する属性として［ `loaded＠~XHR#dom-progressevent-loaded$c, `total＠~XHR#dom-progressevent-total$c, 等々 ］を追加する。 ◎ This usually involves a new subclass of Event, with new attributes to hold the state. ◎ For example, the ProgressEvent adds loaded, total, etc. attributes to hold the state.

• ある~algoを成す異なる各部が協調する必要がある場合、［ 先送りされた~eventを発火するとき，状態を［ 検分する／変更する ］挙動がきちんと定義されるようになる ］ことを確保するため， 明示的な状態~機械（きちんと定義された状態~遷移）を定義する必要もあろう。 ◎ if different parts of an algorithm need to coordinate, you may need to define an explicit state machine (well-defined state transitions) to ensure that when a deferred event fires, the behavior of inspecting or changing state is well-defined.

  【！class="informative】

  例えば， `payment-request$r における `PaymentRequest$I の `state＠~PAYMENT-REQUEST#dfn-state$sl 内部~slotは、 きちんと定義された遷移を通して，当の~objの状態を明示的に追跡する： ◎ For example, in [payment-request], the PaymentRequest's [[state]] internal slot explicitly tracks the object’s state through its well-defined transitions.

  これらの状態~遷移は、 状態~遷移が適切に起こるのを確保するため，防護-法の技法を利用することが多い。 例えば， `payment-request$r は、 `show()＠~PAYMENT-REQUEST#dom-paymentrequest-show$c など用の~algo内で `state＠~PAYMENT-REQUEST#dfn-state$sl 内部~slotの周りで利用される防護-を注記する。 ◎ These state transitions often use the guarding technique themselves, to ensure the state transitions happen appropriately. ◎ For example, in [payment-request] note the guards used around the [[state]] internal slot, such as in the show() algorithm.

• 先送りされた~eventに［ 加的な状態／状態~機械 ］は必要ない場合、 これは おそらく，［ 当の~eventは当の~algoの完了を通達するだけである ］ことを意味する。 これに該当する場合、 当の~APIは，おそらく 当の~eventを発火する代わりに `Promise$c を返すべきである。 `§ 一度限りの~event用には，~promiseを利用すること＠#one-time-events$ を見よ。 ◎ if the deferred event doesn’t need extra state, or a state machine, this probably means that the event is just signalling the completion of the algorithm. If this is true, the API should probably return a Promise instead of firing the event. See § 7.1 Use promises for one time events.

注記： この節に述べたような再帰のアリ性を公開する~eventは， “同期的な~event” と称されることもあるが、 この語法は忌避される — それは、 ~eventは非同期的に配送されることもアリなことを含意するので。 すべての~eventは、 同期的に配送される。 “非同期的な~event” は、 むしろ，~eventの発火を先送りすることを含意することが多い。 ◎ Note: events that expose the possibility of recursion as described in this section were sometimes called "synchronous events". This terminology is discouraged as it implies that it’s possible to dispatch an event asynchronously. All events are dispatched synchronously. What is more often implied by "asynchronous event" is to defer firing an event.

7.7. 状態~用には素な `Event^I を利用すること

アリな所では、 指定された~event型 （ `type＠~DOM4#dom-event-type$c ） を伴う素な `Event$I を利用した上で， 状態~情報を `target＠~DOM4#dom-event-target$c ~obj内に捕捉すること。 ◎ Where possible, use a plain Event with a specified type, and capture any state information in the target object.

`Event$I の新たな下位classを作成することは、 通例的には，必要yでない。 ◎ It’s usually not necessary to create new subclasses of Event.

7.8. ~eventか観測器か適切な方を利用すること

一般に、 観測器【 `Observer^en 】~patternよりも［ `EventTarget$I と通知 `Event$I ］を利用すること — `EventTarget$I では，当の特能~用にきちんと働けない場合を除いて。 ◎ In general, use EventTarget and notification Events, rather than an Observer pattern, unless an EventTarget can’t work well for your feature.

`EventTarget$I を利用すれば、 当の特能は，共有される基底~classに対する改善 — `once＠~DOM4#dom-addeventlisteneroptions-once$c の追加など — から便益を得ることも確保される。 ◎ Using an EventTarget ensures your feature benefits from improvements to the shared base class, such as the addition of the once.

~eventを利用すると問題 — `再帰＠#guard-against-recursion$を避けれないなど — の原因になる場合、 代わりに観測器~patternを利用することを考慮すること。 ◎ If using events causes problems, such as unavoidable recursion, consider using an Observer pattern instead.

観測器~patternの例には、 次が挙げられる ⇒＃ `MutationObserver$I, `IntersectionObserver$I, `ResizeObserver$I, `IDBObserver$I ◎ MutationObserver, Intersection Observer, Resize Observers, and IndexedDB Observers are all examples of an Observer pattern.

観測器~patternは、 次の様に働く： ◎ The Observer pattern works like this:

• 観測器~classの各~instanceは、 ~callback, および任意選択で［ 何が観測されるべきか~custom化するための，何らかの~option群 ］を伴って構築される。 ◎ Each instance of the Observer class is constructed with a callback, and optionally with some options to customize what should be observed.
• 各~instanceは、 `observe()^c と命名された~methodを利用して，特定の~targetを観測し始める — ~methodは、 観測される~targetへの参照をとる。 何が観測されるべきか~custom化するための~option群も， 構築子の代わりに ここで供され得る。 構築子に供された~callbackは、 その~targetに何か関心事が起きたとき，呼出される。 ◎ Instances begin observing specific targets, using a method named observe(), which takes a reference to the target to be observed. The options to customize what should be observed may be provided here instead of to the constructor. The callback provided in the constructor is invoked when something interesting happens to those targets.
• ~callbackは、 引数として `変更~記録^em を受取る。 これらの記録は、 それを起こした関心事についての詳細を包含する。 一度に複数個の記録が送達され得る。 ◎ Callbacks receive change records as arguments. These records contain the details about the interesting thing that happened. Multiple records can be delivered at once.
• 作者は、 観測器~instanceの［ `unobserve()^c ／ `disconnect()^c ］と称される~methodを~callすることにより，観測するのを停止できる。 ◎ The author may stop observing by calling a method called unobserve() or disconnect() on the Observer instance.
• 生じた事象のうち［ 観測されたが まだ送達されていないものすべて ］の記録を即時に返すための~methodも、 任意選択で供され得る。 ◎ Optionally, a method may be provided to immediately return records for all observed-but-not-yet-delivered occurrences.

function checkElementStillVisible(%element, %observer) {
    delete %element.visibleTimeout;

    /* 
まだ`~task~queue$に残っている観測nがあれば，それらを処理する
◎
Process any observations which may still be on the task queue
 */
    processChanges(%observer.takeRecords());

    if ('isVisible' in %element) {
        delete %element.isVisible;
        logAdImpressionToServer();

        /* 
%element の観測を停止する
◎
Stop observing this element
 */
        %observer.unobserve(%element);
    }
}

function processChanges(%changes) {
    %changes.forEach(function(%changeRecord) {
        var %element = %changeRecord.target;
        %element.isVisible = isVisible(%changeRecord.boundingClientRect,
                                      %changeRecord.intersectionRect);
        if ('isVisible' in %element) {
            /* 
%element は可視になった
◎
Element became visible
 */
            %element.visibleTimeout = setTimeout(() => {
                checkElementStillVisible(%element, %observer);
            }, 1000);
        } else {
            /* 
%element は非可視になった
◎
Element became hidden
 */
            if ('visibleTimeout' in %element) {
                clearTimeout(%element.visibleTimeout);
                delete %element.visibleTimeout;
            }
        }
    });
}

/* 
~callbackと~option群で
`IntersectionObserver$I を作成する
◎
Create IntersectionObserver with callback and options
 */
var %observer = new IntersectionObserver(processChanges, { threshold: [0.5] });

/* 
"ad" 要素を観測し始める
◎
Begin observing "ad" element
 */
var %ad = document.querySelector('#ad');
%observer.observe(%ad);

観測器~patternを利用するためには、 次を表現するための~obj型を定義する必要がある ⇒＃ 新たな観測器（以下では “~Observer” と総称される）, 観測n~option群, 観測された記録 ◎ To use the Observer pattern, you need to define: • the new Observer object type, • an object type for observation options, and • an object type for the records to be observed.

この加的な作業には、 ~trade-offとして，次に挙げる利点がある： ◎ The trade-off for this extra work is the following advantages:

• 各~instanceは、［ 作成~時点／観測し始める時点 ］に~custom化できる。 ~Observer の［ 構築子 ／ `observe()^c ~method ］は、［ 各~callback用に，何が観測されるかを~custom化すること ］を作者に許容するためとして，~option群をとれる。 これは `addEventListener()$c ではアリでない。 ◎ Instances can be customized at observation time, or at creation time. The constructor for an Observer, or its observe() method, can take options allowing authors to customize what is observed for each callback. This isn’t possible with addEventListener().
• 複数個の~callbackを~listenしているときでも、 ~Observer ~objの［ `disconnect()^c ／ `unobserve()^c ］~methodを利用すれば，容易に停止できる。 ◎ It’s easy to stop listening on multiple callbacks using the disconnect() or unobserve() method on the Observer object.
• `takeRecords()^c の様な — ~eventが発火されるまで待機する代わりに，関連な~dataを即時に~fetchするような — ~methodを供する~optionもある。 ◎ You have the option to provide a method like takeRecords(), which immediately fetches the relevant data, instead of waiting for an event to fire.
• 観測器は単-目的なので、 ~event型を指定する必要は無い。 ◎ Because Observers are single-purpose, you don’t need to specify an event type.

~Observer と `EventTarget$I の共通~~点は： ◎ Observers and EventTargets have these things in common:

• どちらも，作成~時に~custom化できる。 ◎ Both can be customized at creation time.
• どちらも，一連の生じた事象を~batchでき, どの時点でも送達できる。 `EventTarget$I は、 同期的になる必要はない — 送達する時機には［ `小task$, `遊休~期間＠~REQUESTIDLECALLBACK#dfn-idle-period$, `~animation~frame＠~HTMLGAPI#animation-frames$, 等々 ］を利用できる。 ~Observer は、 特別な［ 時機／~batch法 ］を取得する必要はない。 ◎ Both can batch occurrences and deliver them at any time. EventTargets don’t need to be synchronous; they can use microtask timing, idle timing, animation-frame timing, etc. You don’t need an Observer to get special timing or batching.
• どちらも，~DOM~tree（［ 浮上／捕捉 ］と取消n）に関与する必要はない。 `EventTarget$I として真っ先に挙がるものは，~DOM~tree内の `Node$I であるが、 他の多くの~eventも自立的である — 例： `IDBDatabase$I, `XMLHttpRequestEventTarget$I 。 `Node$I を利用しているときでも，~eventは［ 浮上しない／取消-可能でない ］ものに設計し得る。 ◎ Neither EventTargets nor Observers need to participate in a DOM tree (bubbling/capture and cancellation). Most prominent EventTargets are Nodes in the DOM tree, but many other events are standalone; for example, IDBDatabase and XMLHttpRequestEventTarget. Even when using Nodes, your events may be designed to be non-bubbling and non-cancelable.

const %io = new ETIntersectionObserver(%element, { %root, %rootMargin, %threshold });

function listener(%e) {
    for (const %change of %e.changes) {
        // ...
    }
}

%io.addEventListener("intersect", %listener);
%io.removeEventListener("intersect", %listener);

次も見よ ⇒＃ `§ 通知~用には~eventを利用すること＠#events-are-for-notification$／ § 状態~用には素な `Event^I を利用すること ◎ See also: • § 7.5 Use events for notification • § 7.7 Use plain Events for state

8.1. 数量-型を適切に利用すること

設計している~APIが~JS `number^jT 【~JS `Number$jT 型の値。以下、単に `number^jT と略記する】 を利用する場合、 次に挙げるいずれかの`~IDL数量-型$ `WEBIDL$r を利用すること — そうしない特有な理由がない限り： ◎ If an API you’re designing uses numbers, use one of the following [WEBIDL] numeric types, unless there is a specific reason not to:

`unrestricted double$c

任意の `number^jT — ［ `infinity^jv, `-infinity^jv, `NaN^jv ］も含む ◎ Any JavaScript number, including infinities and NaN

`double$c

任意の `number^jT — ［ `infinity^jv, `-infinity^jv, `NaN^jv ］は含まない ◎ Any JavaScript number, excluding infinities and NaN

`EnforceRange$xA `long long$c

任意の `number^jT のうち［ −2<sup>63</sup> 以上 2<sup>63</sup> 以下 ］のもの — 最も近い整数に丸められる。 この範囲に入らない `number^jT が与えられた場合、 生成される言語束縛は `TypeError$E を投出することになる。 ◎ Any JavaScript number from -263 to 263, rounded to the nearest integer. If a number outside this range is given, the generated bindings will throw a TypeError.

`EnforceRange$xA `unsigned long long$c

任意の `number^jT のうち［ 0 以上 2<sup>64</sup> 以下 ］のもの — 最も近い整数に丸められる。 この範囲に入らない `number^jT が与えられた場合、 生成される言語束縛は `TypeError$E を投出することになる。 ◎ Any JavaScript number from 0 to 264, rounded to the nearest integer. If a number outside this range is given, the generated bindings will throw a TypeError.

~JSの数量-型は、 `Number$jT しかなく，それは［ ~IEEE 754 倍精度~浮動小数点~数, `0^jv, `-0^jv, `infinity^jv, `-infinity^jv, `NaN^jv ］を含む。 `~IDL数量-型$は、 任意の `number^jT を，ある［ 特定0の~propを伴う下位集合 ］に所属するよう改変するための規則を表現する。 これらの規則は、 `number^jT が~IDLにて定義される~interfaceの［ ~method／~prop設定子 ］に渡されたとき，走る。 ◎ JavaScript has only one numeric type, Number: IEEE 754 double-precision floating point, including ±0, ±Infinity, and NaN. [WEBIDL] numeric types represent rules for modifying any JavaScript number to belong to a subset with particular properties. These rules are run when a number is passed to the interface defined in IDL, whether a method or a property setter.

`number^jT に適用される必要がある加的な規則がある場合、 当の仕様の~algo内で指定できる。 ◎ If you have extra rules which need to be applied to the number, you can specify those in your algorithm.

`bigint$c の利用は、 ~~絶対値が 2⁵³ を超える値が予期されるときに限るべきである。 ◎ bigint should be used only when values greater than 253 or less than -253 are expected.

~APIは、［ `BigInt$jT, `Number$jT ］の両方を — ［ 多形態性【すなわち，`共用体~型$】を介して両~型を~supportする／ 別々な，他は一致するが［ `BigInt$jT をとる~API, `Number$jT をとる~API ］を追加する【すなわち，`多重定義-$する】 ］ことにより — 同時に~supportするべきでない。 これには、 暗黙的な変換を通して精度を失う~riskがあり， `BigInt$jT の目的を無為にする。 ◎ An API should not support both BigInt and Number simultaneously, either by supporting both types via polymorphism, or by adding separate, otherwise identical APIs which take BigInt and Number. This risks losing precision through implicit conversions, which defeats the purpose of BigInt.

8.2. 文字列を適切に表現すること

`文字列$に対し演算する~web~platform特能を設計するときは、 特有な理由がある場合を除き， `DOMString$c を利用すること。 ◎ When designing a web platform feature which operates on strings, use DOMString unless you have a specific reason not to.

ほとんどの文字列~演算は、 文字列の内側の`符号単位$を解釈する必要はないので， `DOMString$c が最善な選択になる。 下に説明される特定の事例では、 代わりに［ `USVString$c ／ `ByteString$c ］を利用する方が適切になるかもしれない。 `INFRA$r `WEBIDL$r ◎ Most string operations don’t need to interpret the code units inside of the string, so DOMString is the best choice. In the specific cases explained below, it might be appropriate to use either USVString or ByteString instead. [INFRA] [WEBIDL]

`USVString$c は、 `~scalar値~文字列$を表現する~Web~IDL型である。 次に挙げるもの用には、 `USVString$c を利用するべきである： ◎ USVString is the Web IDL type that represents scalar value strings.＼

• 文字列のうち，最も共通的な~algoは`~scalar値$に対し演算するもの （`~percent-符号化法＠~URL1#percent-encode$など） ◎ For strings whose most common algorithms operate on scalar values (such as percent-encoding),＼
• 入力~内の`~surrogate$を取扱えない演算 （文字列を~nativeな~platform~APIに そのまま渡す~APIなど） ◎ or for operations which can’t handle surrogates in input (such as APIs that pass strings through to native platform APIs),＼ ↑ USVString should be used.

`ByteString$c は、［ ~HTTPの様な，~byte列と文字列を判別しない~protocol ］からの~dataを表現するために限り，利用するべきである。 それは、 一般~目的な文字列~型ではない。 `byte$c たちが成す`連列~型$を表現する必要がある場合、 `Uint8Array$c を利用すること。 ◎ ByteString should only be used for representing data from protocols like HTTP which don’t distinguish between bytes and strings. It isn’t a general-purpose string type. If you need to represent a sequence of bytes, use Uint8Array.

8.3. 時間~測定には~milli秒を利用すること

設計している~APIが時間~測定を受容する場合、 時間~測定を~milli秒で表出すること。 ◎ If you are designing an API that accepts a time measurement, express the time measurement in milliseconds.

当の~APIの分野においては秒（または他の何らかの時間~単位）の方が自然であっても、 ~milli秒を堅持することは，当の~APIが別の~APIと相互運用可能になることを確保する。 これは、 作者にとって［ ある~APIで利用される値を別の~APIに利用するために変換する／ どこで, どの時間~単位が必要になるか追跡し続ける ］必要がなくなることを意味する。 ◎ Even if seconds (or some other time unit) are more natural in the domain of an API, sticking with milliseconds ensures that APIs are interoperable with one another. This means that authors don’t need to convert values used in one API to be used in another API, or keep track of which time unit is needed where.

この規約は、［ `setTimeout()＠~HTMGAPI#dom-settimeout$c ／ `Date$jT ］~APIから始まり，その頃から利用されている。 ◎ This convention began with setTimeout() and the Date API, and has been used since then.

注記： 高分解能な時刻は、 通例的に小数を伴う~milli秒として表現され，浮動小数点~値を利用している — ~nano秒の様な より小さな時間~単位による整数~値としてではなく。 ◎ Note: high-resolution time is usually represented as fractional milliseconds using a floating point value, not as an integer value of a smaller time unit like nanoseconds.

8.4. 時刻と日付を表現するときは適切な型を利用すること

~platformで日時を表現するときは、 `DOMHighResTimeStamp$I 型を利用すること。 `DOMHighResTimeStamp$I は、 利用者の時刻~設定に関わらず，時刻印を比較することを許容する。 ◎ When representing date-times on the platform, use the DOMHighResTimeStamp type. DOMHighResTimeStamp allows comparison of timestamps, regardless of the user’s time settings.

`DOMHighResTimeStamp$I 値は、 時刻~値を~milli秒で表現する。 詳細は `HIGHRES-TIME$r を見よ。 ◎ DOMHighResTimeStamp values represent a time value in milliseconds. See [HIGHRES-TIME] for more details.

~JS `Date$jT ~classは、 特定の日時~値を表現するためとして，利用しないこと。 `Date$jT ~objは変異-可能であり（それらの値は、変更され得る）， それを変異-不能にする仕方は無い。 ◎ Don’t use the JavaScript Date class for representing specific date-time values. Date objects are mutable (may have their value changed), and there is no way to make them immutable.

注記： なぜ `Date$jT を利用してはナラナイかの背景0は、 次を見よ ⇒＃ `es-discuss^en における `Frozen date objects?＠https://esdiscuss.org/topic/frozen-date-objects$en ／ ~Web~IDL `Bugzilla^en における`~Web~IDLから Date を除去する＠https://www.w3.org/Bugs/Public/show_bug.cgi?id=22824$ ◎ For more background on why Date must not be used, see the following: • Frozen date objects? on es-discuss • Remove Date from Web IDL on the Web IDL Bugzilla

8.5. ~error用には `Error^I ／ `DOMException^I を利用すること

~web~APIにおける~errorは、［ 例外, ~promise用の却下~値, ~prop ］いずれにせよ，［ ~ES~error~obj【`単純~例外$】（例：`Error$E ）／ `DOMException$I ］として表現すること。 ◎ Represent errors in web APIs as ECMAScript error objects (e.g., Error) or as DOMException. whether they are exceptions, promise rejection values, or properties.

9.1. 装置についての情報を不必要に公開しないこと

装置についての情報への~accessを~web~siteに与える必要がある場合には、 `利用者~dataを最小~化する原則＠#data-minimization$に倣って， 公開する~dataの量を必要yな~~最小限に抑えること。 ◎ In line with the Data Minimization principle, if you need to give web sites access to information about a device, only expose the minimal amount of data necessary.

まず，［ 装置について識別する情報をすべて公開することは，本当に必要yであるかどうか ］を注意深く考すること。 `利用者の必要性＠#priority-of-constituencies$は， 強力さに劣る~APIでも満足されるかどうか考慮すること。 ◎ Firstly, think carefully about whether it is really necessary to expose identifying information about the device at all. Consider whether your user needs could be satisfied by a less powerful API.

装置の有無や［ 装置／装置~識別子 ］についての情報を追加的に公開することは、 各~利用者の~privacyを害する~riskを増やす。 ◎ Exposing the presence of a device, additional information about a device, or device identifiers, each increase the risk of harming the user’s privacy.

所与の［ ~sensor／能力 ］に対し，［ それを利用する許可を利用者が却下したこと, それが無いこと ］は、 ~web~appからは判別-不能にするベキである。 ◎ A web app should not be able to distinguish between the user rejecting permission to use a sensor/capability, and the sensor/capability not being present.

特有な情報が共有されるほど，~siteに可用になる`指紋収集~data＠~TR/fingerprinting-guidance/$は~~増す。 利用者の~privacyには、 `他の~riskの能性＠~PRIVACY-PRINCIPLES#threats$もある。 ◎ As more specific information is shared, the fingerprinting data available to sites gets larger. There are also [other potential risks](Privacy Principles § threats) to user privacy.

強力さに劣る~APIを設計する仕方は無い場合、 装置~情報を公開するときは，次に挙げる指針を利用すること： ◎ If there is no way to design a less powerful API, use these guidelines when exposing device information:

当の~ID内の情報は制限すること： ◎ Limit information in the id

~web~platformに公開される装置~ID内に含める識別-可能な情報は、 アリな限り抑えること。 識別-可能な情報として、 銘柄, 製造元, ~model番号, 等々が挙げられる。 通例的には、 代わりに［ ~randomな数／一意な~ID† ］を利用できる。 ~IDは、 推測-不能かつ再利用されないようにすること。 【†この “一意” とは、他の~IDと等しいか否か比較すること以外の能力を与えないことを意味する。】 ◎ Include as little identifiable information as possible in device ids exposed to the web plaform. Identifiable information includes branding, make and model numbers, etc You can usually use a random number or a unique id instead. Make sure that your ids aren’t guessable, and aren’t re-used.

利用者の制御~下に保つこと： ◎ Keep the user in control

利用者が閲覧~dataを~clearするよう選んだときは、 格納された装置~IDも~clearすること。 ◎ When the user chooses to clear browsing data, make sure any stored device ids are cleared.

敏感な~IDは利用者~許可の背後に隠すこと： ◎ Hide sensitive ids behind a user permission

装置~IDを匿名な仕方で作成できない場合、 それへの~accessを制限すること。 この情報に~accessしている~web~pageに対し， 利用者が`有意義な同意＠#consent$を供せるようにすること。 ◎ If you can’t create a device id in an anonymous way, limit access to it. Make sure the user can provide meaningful consent to a Web page accessing this information.

~IDを同一-生成元~modelに束ねること： ◎ Tie ids to the same-origin model

同じ物理-装置に対し、 それへの~accessを有する各~生成元ごとに，別個な一意な~IDを作成すること。 ◎ Create distinct unique ids for the same physical device for each origin that has has access to it.

同じ装置が同じ生成元により複数回 要請された場合、 それ用には同じ~IDを返すこと （利用者が自身の閲覧~dataを~clearした場合は除く）。 これは、［ 同じ装置【を表現する~data】をいくつも複製することを避ける ］ことを作者に許容する。 ◎ If the same device is requested more than once by the same origin, return the same id for it (unless the user has cleared their browsing data). This allows authors to avoid having several copies of the same device.

必要yなら、 持続-可能にすること： ◎ Persistable when necessary

装置~IDを得するのに時間がかかる場合、 作者が［ ある~sessionで生成された~IDを後の~sessionにおける利用~用に格納できる ］ようにすること。 これは、 次のようにすることにより行える ⇒ 当の~IDを生成する手続-は、［ 同じ生成元，同じ装置 ］に対しては，一貫して同じ~IDを生産する ◎ If a device id is time consuming to obtain, make sure authors can store an id generated in one session for use in a later session. You can do this by making sure that the procedure to generate the id consistently produces the same id for the same device, for each origin.

次も見よ ⇒＃ `LEAST-POWER$r／ `FINGERPRINTING-GUIDANCE$r／ `UNSANCTIONED-TRACKING$r ◎ See also: • [LEAST-POWER] • [FINGERPRINTING-GUIDANCE] • [UNSANCTIONED-TRACKING]

9.2. 装置を［選定する／列挙する］~APIを公開するときの注意点

各~装置を列挙するのは避ける仕方を探すこと。 避けれない場合でも、 公開される情報はアリな限り少量にすること。 ◎ Look for ways to avoid enumerating devices. If you can’t avoid it, expose the least information possible.

ある~APIが複数個の装置の［ 存在／能力／識別子 ］を公開する場合、 `§ 装置についての情報を不必要に公開しないこと＠#device-ids$ におけるすべての~riskが，装置の個数だけ乗算される。 同じ理由で、［ `利用者の必要性＠#priority-of-constituencies$が強力さに劣る~APIでも満足できるかどうか ］を考慮すること。 `LEAST-POWER$r ◎ If an API exposes the the existence, capabilities, or identifiers of more than one device, all of the risks in § 9.1 Don’t expose unnecessary information about devices are multiplied by the number of devices. For the same reasons, consider whether your user needs could be satisfied by a less powerful API. [LEAST-POWER]

~APIの目的が［ 特定0の種類の可用な装置たちが成す集合から`装置を選定する^strongこと ］を利用者に可能化することにある場合、 その~listを~scriptに公開する必要はまったくなく， ~UAが供した装置~pickerを呼出す~APIで足り得るであろう。 そのような~APIは： ◎ If the purpose of the API is to enable the user to select a device from the set of available devices of a particular kind, you may not need to expose a list to script at all. An API which invokes a User-Agent-provided device picker could suffice. Such an API:

• 利用者の制御~下に保つこと。 ◎ keeps the user in control,
• 装置~情報は、 `利用者の同意＠#consent$を経ない限り，公開しないこと, ◎ doesn’t expose any device information without the user’s consent,
• 既定では、 利用者の環境についての指紋収集~dataを公開しないこと。 ◎ doesn’t expose any fingerprinting data about the user’s environment by default, and
• 一回に情報を公開する装置の個数は 1 個に限ること。 ◎ only exposes information about one device at a time.

［ 装置を選定することを利用者に許容する~API ］を設計するとき，［ 選び取られた装置が可用である事実 ］も公開することが必要yあり得る。 これは、［ 利用者の環境についての一片の指紋収集~data ］を~web~siteに公開するので、 そのような特能を備えない~APIほどには安全でない。 ◎ When designing API which allows users to select a device, it may be necessary to also expose the fact that there are devices are available to be picked. This does expose one bit of fingerprinting data about the user’s environment to websites, so it isn’t quite as safe as an API which doesn’t have such a feature.

装置たちが成す~listを公開しなければナラナイ場合、［ 利用者の必要性を満足するために`~~最小限な下位集合^strongを公開する ］よう努めること。 ◎ If you must expose a list of devices, try to expose the smallest subset that satisfies your user needs.

例えば［ `絞込まれ, 拘束された^strong装置~listを要請する ］ことを~web~siteに許容する~APIは、 装置の個数をより少なく保つ~optionの一つを成す。 しかしながら，［ 異なる拘束を伴う，複数個の要請 ］を為すことが作者に許容された場合、 それにより，全部的な~listに~access可能になり得る。 ◎ For example, an API which allows the website to request a filtered or constrained list of devices is one option to keep the number of devices smaller. However, if authors are allowed to make multiple requests with different constraints, they may still be able to access the full list.

最後に，特定0の種類に属する装置~群の全部的な~listを公開しなければナラナイ場合、 それら装置が~listされる順序を`厳格に定義する^strongこと。 これは、 相互運用能の課題を抑制し得ることに加え，指紋収集を軽減する助けにもなる。 （~sort順序は、 他の情報を露呈することもある — `~web仕様における~browser指紋収集の軽減-法^cite `§ 標準~化＠https://w3c.github.io/fingerprinting-guidance/#standardization$ を見よ。） ◎ Finally, if you must expose the full list of devices of a particular kind, please rigorously define the order in which devices will be listed. This can reduce interoperability issues, and helps to mitigate fingerprinting. (Sort order could reveal other information: see Mitigating Browser Fingerprinting in Web Specifications § 6.2 Standardization for more.)

注記： ~APIは、 装置の全部的な~listを`実装定義$な順序で公開するべきではないが，~web互換性の理由からそれが必要になることもある。 ◎ Note: While APIs should not expose a full list of devices in an implementation-defined order, they may need to for web compatibility reasons.

9.3. 下層の~APIや~hardwareではなく利用者の必要性に基づいて設計すること

~webに持込まれる新たな~native能力は、 利用者の必要性に基づいて公開すること。 ◎ Expose new native capabilities being brought to the web based on user needs.

既存の~native~APIを~webへ直に翻訳するのは避けること。 ◎ Avoid directly translating an existing native API to the web.

代わりに，［ 当の~native~APIにて可用な機能性, それが取組む利用者の必要性 ］を考慮して、 実装が既存の~native~APIに依存する場合でも， 利用者の必要性を満たす~APIを設計すること。 ◎ Instead, consider the functionality available from the native API, and the user needs it addresses, and design an API that meets those user needs, even if the implementation depends on the existing native API.

下層の~native~APIの正確な［ ~lifecycle／~data構造 ］を公開することについて、 特に気を付けること。 アリなときは、 新たな~hardware用の柔軟性を考慮すること。 ◎ Be particularly careful about exposing the exact lifecycle and data structures of the underlying native APIs. When possible, consider flexibility for new hardware.

このことは、 新たに提案される~APIは，［ それが，どう利用されるものと意図されるか ］を注意深く考慮する下で設計されるべきであることを意味する — 下層の［ ~hardware／装置／~native~API ］が今日にて どう可用かではなく。 ◎ This means newly proposed APIs should be designed with careful consideration on how they are intended to be used rather than how the underlying hardware, device, or native API available today.

9.4. 安全性について事前に備えておくこと

~web~platformに~native能力を持込むときは、 防御的に設計するよう努めること。 ◎ When bringing native capabilities to the web platform, try to design defensively.

~native能力を~web~platformに持込むことには、 多くの含意がつきまとう。 利用者は、 自身の~computerが特有な能力を備えることを~web~siteに知らせたいとは求めないであろう。 したがって，論理的な生成元~境界の外側にある何かへの~accessは、 許可を介して通過制御されるべきである。 ◎ Bringing a native capability to the web platform comes with many implications. Users may not want websites to know that their computers have specific capabilities. Therefore, access to anything outside of the logical origin boundary should be permission gated.

例えば，［ 状態を格納し得る装置があって，その状態は複数の生成元から同時に読取n可能である ］場合、 その状態を一群の~APIから［ 読取れる／書込める ］ようにすることは，実質的に［ ~webの生成元~modelを損なう~side-channel【〜攻撃の余地を与えるもの】 ］になる。 ◎ For example, if a device can store state, and that state is readable at the same time by multiple origins, a set of APIs that lets you read and write that state is effectively a side-channel that undermines the origin model of the web.

これらの理由から、 当の装置が排他的でない~accessを許容する場合でも，［ 生成元ごとに排他的な~accessを施行するか、 更には，現在~作動中な~UItabに限るよう制約する ］ことを考慮することになろう。 ◎ For these reasons, even if the device allows non-exclusive access, you may want to consider enforcing exclusive access per-origin, or even restricting it further to only the current active tab.

加えて，~APIは、 物理的な遮断 — 当の装置がとり外されているなど — を~appが上品に取扱えるよう，設計されるべきである。 ◎ Additionally, APIs should be designed so that the applications can gracefully handle physical disruption, such as a device being unplugged.

9.5. ~native~APIに順応するときは、~web~platform原則を利用すること

~OSに~nativeな~APIを~web用に順応するときは、 ~web~platform原則を念頭に置いて，新たな~web~APIを設計すること： ◎ When adapting native operating system APIs for the web, make sure the new web APIs are designed with web platform principles in mind.

~web~APIは、 複数の~platformで実装できるようにすること。 ◎ Make sure the web API can be implemented on more than one platform

何かを包装する~APIを設計するときは、 各種~platformが その機能性をどう供するか考慮すること。 ◎ When designing a wrapper API, consider how different platforms provide its functionality.

理想的には，すべての実装が正確に同じに働くべきであるが、 一部の事例では，一部の~platformでしか働かない~optionを公開する理由もあろう。 それに該当する場合、［ 作者は、 すべての~platformで働く~codeを どう書するべきか ］を説明すること。 `§ 新たな特能は検出-可能になるべきである＠#feature-detect$を見よ。 ◎ Ideally, all implementations should work exactly the same, but in some cases you may have a reason to expose options which only work on some platforms. If this happens, be sure to explain how authors should write code which works on all platforms. See § 2.5 New features should be detectable.

下層の~protocolは、 ~openになるべきである ◎ Underlying protocols should be open

外部［ ~hardware／~service ］との交換を要求する~APIは、［ ~openでない／~proprietaryな ］~protocolに依存するべきでない。 ~openでない~protocolに依存することは、 ~webの~openな資質を損なう。 ◎ APIs which require exchange with external hardware or services should not depend on closed or proprietary protocols. Depending on non-open protocols undermines the open nature of the web.

利用者が~off-lineであるときも取扱うよう，~APIを設計すること ◎ Design APIs to handle the user being off-line

~APIが［ ~remote~serverにより供される何らかの~service ］に依存する場合、［ 利用者が何らかの理由で~remote~serverに~accessできないとき ］でも，~APIがきちんと機能するようにすること。 ◎ If an API depends on some service which is provided by a remote server, make sure that the API functions well when the user can’t access the remote server for any reason.

追加的な指紋収集~表口を避けること ◎ Avoid additional fingerprinting surfaces

何かを包装する~APIは、 意図的でなくとも，より広い指紋収集~表口に利用者を晒し得る。 追加的な詳細は、 ~TAGによる知見 `野放図な追跡＠https://www.w3.org/2001/tag/doc/unsanctioned-tracking/$cite を読されたし。 ◎ Wrapper APIs can unintentionally expose the user to a wider fingerprinting surface. Please read the TAG’s finding on unsanctioned tracking for additional details.

10.1. 新たな特能~用には~polyfillを可能化すること

~polyfillは、 新たな特能が~web~platformに普及する助けになるものとして，多大に有益になり得る。 ~TAGによる `~polyfillと~webの発展に対する知見＠https://www.w3.org/2001/tag/doc/polyfills/$cite は、 新たな特能の開発において考慮されるべき指導を提供する — 特に： ◎ Polyfills can be hugely beneficial in helping to roll out new features to the web platform. The Technical Architecture Group finding on Polyfills and the Evolution of the Web offers guidance that should be considered in the development of new features, notably:

• “~polyfill可能” であることは、 本質的ではないが，`有益である^strong。 ◎ Being "polyfillable" isn’t essential but is beneficial
• `§ 新たな特能は検出-可能になるべきである＠#feature-detect$。 ◎ § 2.5 New features should be detectable
• ~polyfillの開発は、 奨励されるべきである。 ◎ Polyfill development should be encouraged

10.2. ~APIはアリな所では専用~workerにも可用にされるベキである

特能を公開するときは、［ 当の特能を専用~workerにも （ `DedicatedWorkerGlobalScope$I ~interfaceを介して） 公開することはイミを成すかどうか ］について考慮されたし。 ◎ When exposing a feature, please consider whether it makes sense to expose the feature to dedicated workers (via the DedicatedWorkerGlobalScope interface).

多くの特能は、 専用~worker上でも，そのままで働ける — 当の特能をそこで可能化しないことは、［ その利用者が，自身の~codeを他を阻まない方式で走らす能 ］を制限することにもなり得る。 ◎ Many features could work out of the box on dedicated workers and not enabling the feature there could limit the ability for users to run their code in a non-blocking manner.

ある特能を専用~workerでも公開しようと試行するとき，ある種の難題が存在し得る — とりわけ、 当の特能が［ 許可を依頼する／ ~pickerや選定器を示す ］ような利用者~入力を要求する場合に。 これは［ 仕様~策定者が専用~workerを~supportするのを忌避させる ］かもしれないが，それでも、［ 専用~worker用の~supportを念頭に，当の特能を設計する ］ことが推奨される — ［ 後で，当の~APIを専用~workerに公開する ］ことが［ 不必要に難しくなるような前提 ］を追加しないために。 ◎ Certain challenges can exist when trying to expose a feature to dedicated workers, especially if the feature requires user input by asking for permission, or showing a picker or selector. Even though this might discourage spec authors to support dedicated workers, we still recommend designing the feature with dedicated worker support in mind, in order to not add assumptions that will later make it unnecessarily hard to expose these APIs to dedicated workers.

10.3. 新たな~data形式を適正に追加すること

新たな~data形式に対しては、 常に ⇒＃ 対応する~MIME型を定義すること／ この型を~supportするよう既存の~APIを拡張すること ◎ Always define a corresponding MIME type and extend existing APIs to support this type for any new data format.

~web上の新たな能力が［ 新たな~data形式を追加すること ］も孕む事例がある。 これには、 ~browserが取り込むものと期待される［ 画像／動画／音声／他の型の~data ］も該当し得る。 新たな形式には、［ 厳密に検証されるよう，標準~化された~MIME型 ］があるべきである。 ◎ There are cases when a new capability on the web involves adding a new data format. This can be an image, video, audio, or any other type of data that a browser is expected to ingest. New formats should have a standardized MIME type, which is strictly validated.

旧来の~media形式は，~MIME型に対する厳密な施行を常に行ってはいなかったが （これに対処するため、 ときには，【~media~dataの】~headerを覗見ることに依拠している）、 その理由のほとんどは旧来との互換性を得るためであり，新たな形式には［ 期待される／実装される ］べきでない。 ◎ While legacy media formats do not always have strict enforcement for MIME types (and sometimes rely on peeking at headers, to workaround this), this is mostly for legacy compatibility reasons and should not be expected or implemented for new formats.

仕様~策定者には、 新たな形式を既存の~APIに統合することも期待される — ~browserの視点からは、［ ~~入口（例： `ReadableStream$I から復号するとき）, ~~出口（例： `WritableStream$I【！WriteableStream】 へ符号化するとき） ］どちらにおいても，安全な形式とみなされるよう。 ◎ It is expected that spec authors also integrate the new format to existing APIs, so that they are safelisted in both ingress (e.g. decoding from a ReadableStream) and egress (e.g. encoding to a WriteableStream) points from a browser’s perspective.

例えば，~web~platformに【新たな】画像~形式を追加する場合、 まず，当の形式~用に新たな~MIME型を追加してから、 `HTMLImageElement$I における復号-法を~supportするため必然的に， 当の画像~形式~用の復号器を（および，必要なら符号化器も）追加することになろう。 この~~上層には、 さらに， `HTMLCanvasElement$I の［ `toBlob()＠~HEcanvas#dom-canvas-toblob$c, `toDataURL()＠~HEcanvas#dom-canvas-todataurl$c ］などの~~出口に対する~supportを追加することも期待される。 ◎ For example. if you are to add an image format to the web platform, first add a new MIME type for the format. After this, you would naturally add a decoder (and presumably an encoder) for said image format to support decoding in HTMLImageElements. On top of this, you are also expected to add support to egress points such as HTMLCanvasElement.toBlob() and HTMLCanvasElement.toDataURL().

旧来の理由から，~browserは~MIME型の~sniff法を~supportするが、 その`~pattern照合~algo＠~MIMESNIFF#image-type-pattern-matching-algorithm$を拡張することは，~securityの含意に因り推奨されない — より新たな形式~用には、 代わりに，厳密な~MIME型を施行することが推奨される。 ◎ For legacy reasons browsers support MIME type sniffing, but we do not recommend extending the pattern matching algorithm, due to security implications, and instead recommend enforcing strict MIME types for newer formats.

新たな~MIME型には、 それ用の仕様があるべきであり， ~IANA（ `Internet Assigned Numbers Authority^en ）に登録されるべきである。 ◎ New MIME types should have a specification and should be registered with the Internet Assigned Numbers Authority (IANA).

10.4. 新たな~HTTP~headerは、標準に適合すること

新たな~HTTP~headerを定義している場合、 その構文は， `~HTTP仕様＠~HTTPinfra#fields$ 【！`~HTTP仕様＠~RFCx/rfc7230#section-3.2$】 に反してはナラナイ。 ◎ If you are defining a new HTTP header, its syntax mustn’t go against the HTTP specification.

新たな~headerが有構造~data — ［ ~list／辞書／十進数／文字列／真偽値 ］の様な型を伴う値など — を伝達しなければならない場合、 当の~headerは `~HTTP用の有構造~field値＠~STRUCTURED-FIELDS$ `RFC8941$r に定義される構文を利用するべきである。 これは、 当の~headerの消費器~用に特有な構文解析器を［ 書する, 保守する ］必要を避けることに加え，消費器が既存の構文解析器を非互換化してしまうことも避ける。 新たな~headerが`有構造~field値＠~STRUCTURED-FIELDS#structured-field-name-value$で表現できない~dataを要求する場合、 有構造~field値の構文を拡張することについて~IETFと関わり合うか， 新たな構文を考案する前に［ ~HTTP~headerは~dataを公開する場として当を得ている ］のか考慮し直すこと。 ◎ If the new header must convey structured data, such as lists, dictionaries, or typed values like decimals, strings, or booleans, then the header should use the syntax defined in Structured Field Values for HTTP. This avoids consumers of the header having to write and maintain specific micro-parsers, or even worse, something that would break those existing parsers. If the new header requires data that can’t be represented by Structured Field Values, then either engage with IETF about extending the Structured Field Values syntax, or re-consider if an HTTP header is a right place to expose the data before inventing a new syntax. [RFC8941]

10.5. 既存の~manifest~fileを拡張すること — 新たなそれを作成することなく

当の特能が~manifestを要求する場合、 既存の~manifest~schemaを拡張できるかどうか究明すること。 ◎ If your feature requires a manifest, investigate whether you can extend an existing manifest schema.

新たな~web特能は［ 自己完結的かつ自己記述的 ］になるべきであり、 理想的には，追加的な~manifest~fileを要求するべきでない。 既存の~manifest~fileには、 次に挙げるものが含まれる： ◎ New web features should be self-contained and self-describing and ideally should not require an additional manifest file. Some of the existing manifest files include

• `~web~app~manifest＠~APPMANIFEST$cite （ `Web App Manifest^en ） ⇒ ~web~appに関係する特能を包含する。 ◎ Web App Manifest which contains features related to web applications.
• `支払い~method~manifest＠~TR/payment-method-manifest/$cite （ `Payment Method Manifest^en ） ⇒ ~web支払い~APIの文脈における支払い~method用に利用される。 ◎ Payment Method Manifest which is used for payment methods in the context of the web payment API
• `公表物~manifest＠~TR/pub-manifest/$cite （ `Publication Manifest^en ） ⇒ ~web公表物~WGによる一部の標準で利用される。 ◎ Publication Manifest which is used by some web publications working group standards
• `生成元~施策＠https://wicg.github.io/origin-policy/$cite （ `Origin Policy^en ） ⇒ ~security施策を設定するために利用される。 ◎ Origin Policy which is used to set security policies.

既存の各種~manifest~fileを拡張することが奨励される。 常に、 元の仕様の中に変更を加えるよう試行するか， 少なくとも当の仕様~編集者と拡張について論じること。 この論点があれば、［ 結果の設計は もっと良くなる／ ~platformに もっと良く統合される何かへ至る ］見込みは高まる。 ◎ We encourage people to extend existing manifest files. Always try to get the changes into the original spec, or at least discuss the extension with the spec editors. Having this discussion is more likely to result in a better design and lead to something that better integrates with the platform.

~manifest用に新たな［ ~key, 値 ］を設計するときは、 それらが必要であること （すなわち、 きちんと考出された利用事例を可能化するものであること） を確かめること。 また、 類似な~keyが存在するか検査されたし。 既存の ( ~key / 値 ) ~pairでは，必要なものに~~比して過不足がある場合、 アリなら，既存の仕様と作業して それを当の利用事例へ拡張すること。 ◎ When designing new keys and values for a manifest, make sure they are needed (that is, they enable well-thought-out use-cases). Also, please check if a similar key exists. If an existing key/value pair does more or less what is needed, work with the existing spec to extend it to your use-case if possible.

注記： 元の仕様~策定者は、 一定期間は，当の変更を彼らの~manifest形式に即時に統合したいと求めないかもしれない。 これは、［ （勧告候補へ向けて進む様な）~process／ 当の追加は異なる視野に入ること ］に因ることもある — 例えば，［ `~web~app~manifest^citeに対する拡張に影響される利用事例は、［ 店／支払い ］に限られる ］の様に。 その事例では、 元の仕様の編集者と合意される限り，`~monkey~patchする$ことも受容-可能である。 ◎ There are certain times the original spec authors might not want to integrate changes to their manifest format immediately. This may be due to process (like going to CR), or due to the addition having a different scope, like extensions to Web App Manifest only affecting store or payment use-cases. In that case, it is acceptable to monkey patch as long as that is agreed with the original spec editors.

しかしながら，当の特能に［ 機能上の領分に特有な~metadata ］が成す複階的な集合が要求される場合、 新たな~manifestの作成も正当化されよう。 ◎ However, if your feature requires a complex set of metadata specific to a functional domain, the creation of a new manifest may be justified.

~manifest~fileの領分が既存の~manifest~fileと異なる場合、 新たな~manifest~fileを作る必要もあろう — 例：~fileを~fetchする時機が異なる場合や， ~manifestの複階性が，そうする必要の~~十分な~~根拠を成す場合。 ~app~metadataは、［ `~web~app~manifest^cite, または その拡張 ］に追加されるべきである。 ~manifestのうち［ 特定の~app／ ~browser以外との相互運用能を要求するもの ］用に利用されるものと指名されるものは、 異なる~approachをとる必要もあろう。 これらに該当する事例の例として［ `支払い~method~manifest^cite, `公表物~manifest^cite, `生成元~施策^cite ］がある。 ◎ You may need to make a new manifest file if the domain of the manifest file is different from the existing manifest files. For example, if the fetch timing is different, or if the complexity of the manifest warrants it. Application metadata should be added to the Web App Manifest or be an extension of it. Manifests designated to be used for specific applications or which require interoperability with non-browsers may need to take a different approach. Payment Method Manifest, Publication Manifest, and Origin Policy are examples of these cases.

例えば，~metadata片が一つだけならば — ~fetch時機が既存の~manifestと異なっていても — おそらく，既存の~manifestを利用する （あるいは，理想的には、 ~manifestは要求されない仕方で，当の特能を設計する） のが最善である。 しかしながら，当の特能に［ その機能上の領分に特有な~metadata ］が成す複階的な集合が要求される場合、 新たな~manifestの作成も正当化され得る。 ◎ For example, if you have a single piece of metadata, even if the fetch timing is different than an existing manifest, it is probably best to use an existing manifest (or ideally design the feature in such a way that a manifest is not required). However, if your feature requires a complex set of metadata specific to a functional domain, the creation of a new manifest may be justified.

どの事例でも、 命名~規約と調和するべきであることに注意 （ `§ 命名~原則＠#naming-is-hard$を見よ）。 ◎ Note that in all cases, the naming conventions should be harmonized (see § 12 Naming principles).

注記： 既存の~manifestは、 原則により，~underscoreで区切られた小文字による名前を利用する。 ~DOM~API内の~manifestから辞書を再利用するのが有用であった~~時期もあった — そこでの各~名前は、 ~camel-case化した~versionに変換することが意味されていた。 そのような例には、 `画像~資源＠https://w3c.github.io/image-resource/$ がある。 この理由から、 ~keyを 1 個の単語で明瞭に表出できるなら，そうすることが推奨される。 ◎ Note: By principle, existing manifests use lowercase, underscore-delimited names. There have been times where it was useful to re-use dictionaries from a manifest in DOM APIs as well, which meant converting the names to camel-cased version. One such example is the image resource. For this reason, if a key can clearly be expressed as a single word, that is recommended.

10.6. 直列化するときは消費者を考慮すること

構文解析器や直列化器を孕む特能を［ 追加する／拡張する ］ときは、 それによる直列化に対する効果を考慮するベキである。 直列化の結果の~~対象者として，次に挙げるものを考慮しなければナラナイ： ◎ When adding or extending features that involve a parser or a serializer you should consider their effect on serialization. The following are constituencies of serialization results that must be considered:

• 利用者 ⇒ 直列化の結果は、 末端-利用者に呈示されることもあるので。 ◎ Users - because the result of serialization may be presented to the end user
• ~tool ⇒ いくつかの仕方で，出力を成す直列化に依拠することもあるので （一例として、 構文解析器が入力~内の~errorを正す必要があるか否か検出するために）。 ◎ Tools - which may rely on the output of serialization in a number of ways (for instance, to detect if the parser need to correct for errors in the input)
• ~Web~API ⇒ 直列化は、 ~web~platformの他の~APIへ渡されることもあるので。 ◎ Web APIs - because serializations may be passed into other APIs of the web platform

言語に特有な期待を考慮すること — 一例として、 空白の有無が有意になり得る言語もある。 各~言語が受容する浮動小数点~数の精度は，言語に応じて相違し得る。 直列化の結果は： ◎ Consider language specific expectations - for instance, in some languages, the presence or absence of whitespace may be significant. Languages may differ in the precision of floating point numbers they accept. The results of serialization:

• 開発者の期待に合致するベキである （一例として、 ~CSS~propを直列化-法した結果の出力は， ~CSS作者が書したものと大きく異なるベキでない）。 ◎ Should match developer expectations (for instance, serializing CSS properties should not result in output that is very different from what a CSS author would have written)
• `冪等性＠https://en.wikipedia.org/wiki/Idempotence$ ⇒ 構文解析器からの出力を直列化した結果は、 再び構文解析して直列化されたとき，同じ結果を生産するベキである。 ◎ Idempotence - the result of serializing the output of a parser should be something that, when parsed and serialized, produces itself.
• ~error累積に追加するベキでない ⇒ ある~APIから直列化された出力をとって，ある~loop内で同じ~APIへ~feedbackしても、 結果の内部~状態は同じになるベキである。 ◎ Should not add to error accumulation - taking the serialized output of an API and feeding it back to the same API in a loop should result in the same internal state

10.7. 特能が開発者に親切になることを確保すること

新たな特能は、 どれも，開発者に親切になるべきである。 親切さを数値化することは難しいが、 少なくとも次に挙げる点を考慮すること。 ◎ Any new feature should be developer-friendly. While it is hard to quantify friendliness, at least consider the following points.

• 例外に伴われる~error~textは，汎用であるべきだが、 開発者~向けの~error~message（開発者~consoleに示されるものなど）は， 開発者に有意義でなければならない。 開発者が~errorに遭遇したとき、 当の~messageは，［ 汎用に過ぎないよう，当の~error事例に特有なもの ］にするべきである。 ◎ While error text in exceptions should be generic, developer-oriented error messages (such as those from a developer console) must be meaningful. When a developer encounters an error, the message should be specific to that error case, and not overly generic.
• 開発者~向けの~error~messageは、 理想的には，［ 開発者が問題がある箇所を~~特定すること ］を手引きするに十分な情報を伴うべきである。 ◎ Ideally, developer-oriented error messages should have enough information to guide the developer in pinpointing where the problem is.
• ~CSSなどの宣言的な特能は、 ~debug能を得るために，実装において加的な作業が要求され得る。 当の仕様において これを定義することは、 当の特能が より開発者に親切になるのみならず，利用者にとって一貫した開発~体験も確保する。 ◎ Declarative features such as CSS, may require extra work in the implementation for debuggability. Defining this in the specification not only makes the feature more developer-friendly, it also ensures a consistent development experience for the users.

~debug能を仕様の一部として定義した良い例として，次が挙げられる ⇒ `~web~animation^cite（ `Web Animations^en ）の `§ 利用事例＠~WANIM#use-cases$。 ◎ A good example where debuggability was defined as part of the specification is Web Animations.

10.8. 最良な暗号を利用すること，暗号は進化するものと予期すること

暗号用の~algoには、 ~security専門家により公平に考査されたものに限り利用すること — 【~~強度が】立証された, 最新なものを選ぶこと。 暗号用の［ ~protocol／~algo ］は、 廃用にされたり，~secureでなくなるのみならず，急速に進化する。 ◎ Use only cryptographic algorithms that have been impartially reviewed by security experts, and make sure your choice of algorithm is proven, and up-to-date. Not only do they become obsolete or insecure, cryptographic protocols and algorithms also evolve quickly.

10.9. ~client~hintを通して新たな情報を公開しないこと

`~client~hint^cite `RFC8942$r を利用して公開する情報は、 ~web~pageが すでに~accessを有しているものに限ること。 ◎ When using Client Hints, don’t expose information that the web page does not already have access to.

~client~hintは重要な最適化ではあるが、 ~siteに情報を公開する唯一の手段には，なり得ない — それを定義した `RFC8942$r `§ 情報~公開＠~HTTPch#information-exposure$にて~~述べられたとおり： ◎ Client hints are an important optimization, but cannot be the sole means by which information is exposed to sites. As it says in RFC 8942 §4.1 where client hints are defined:

したがって，この文書に依拠する下で~client~hint~headerを定義している特能は、 さもなければ［ ~UAが応用 — 既存の［ 要請~header／~HTML／~CSS／~JS ］など — には可用にしないような，新たな情報 ］を供してはナラナイ。 ◎ Therefore, features relying on this document to define Client Hint headers MUST NOT provide new information that is otherwise not made available to the application by the user agent, such as existing request headers, HTML, CSS, or JavaScript.

追加しようと試行している新たな~client~hintが［ 他の手段では，~web~pageに可用にならない情報 ］を公開するものである場合、 まずは［ そのような情報を~APIを通して公開する ］ことを追求されたし。 ◎ If you are trying to add a new client hint that exposes information that is not available to the web page through other means, please pursue exposing this information through an API first.

11.1. 当の仕様~内の各~要件の対象者を識別すること

次の両者を文書化すること ⇒＃ 当の~APIを利用している作者が良い~codeをどう書するべきか／ 当の~APIの実装者が拙く書された~codeをどう取扱うべきか ◎ Document both how authors should write good code using your API, and how implementers of your API should handle poorly-written code.

~webは — とりわけ他の~platformとの比較において — 拙く形成された~markupを受容することにおいて堅牢に設計されている。 このことは、 次を意味する ⇒＃ ~web~pageが~web標準の旧い~version利用していても，新たな~UAで視れる／ 作者にとって，学習曲線は より~~緩やか（ `shallow^en ）になる【 習得に~~時間がかかる？易しくなる？】 ◎ The web, especially in comparison to other platforms, is designed to be robust in accepting poorly-formed markup. This means that web pages which use older versions of web standards can still be viewed in newer user agents, and also that authors have a shallower learning curve.

これを~supportするため，~web仕様の書者は、 きちんと形成された~markupのみならず，拙く形成された~markupを解釈する方法を述べる必要がある。 ◎ To support this, web specification writers need to describe how to interpret poorly-formed markup, as well as well-formed markup.

実装者は、［ 作者が利用しようと目指しているはずの “適合な言語” ］より複階的な， “~supportされる言語” を理解-可能になる必要がある。 ◎ Implementers need to be able to understand the "supported language", which is more complex than the "conforming language" which authors should be aiming to use.

11.2. 完全に指定して多義性を避けること

特能が，どう働くべきか指定するときは、［ 作者が異なる実装ごとに異なる~codeで作業するよう書する必要がない ］ほど十分な情報を与えること。 ◎ When specifying how a feature should work, make sure that there is enough information so that authors don’t have to write different code to work with different implementations.

仕様による指定が不十分な場合、 実装者は他と異なる選択を為すかもしれず，その場合［ その相違点を取扱うために加的な~codeを書する ］ことを作者に強制することになる。 ◎ If a specification isn’t specific enough, implementers might make different choices which force authors to write extra code to handle the differences.

実装者が［ この状況を避けるために，他の実装の詳細を検査する必要 ］は、 生じるべきでない。 代わりに，仕様は、 それ自体で十分に［ 完全かつ明瞭 ］になるべきである。 ◎ Implementers shouldn’t need to check details of other implementations to avoid this situation. Instead, the specification should be complete and clear enough on its own.

注記： このことは、 実装が許可~promptの様なものを他と［ 異なるように具現化できない ／異なる~UIを示せない ］ことを意味するわけではない。 ◎ Note: This doesn’t mean that implementations can’t render things differently, or show different user interfaces for things like permission prompts.

注記： 実装者は、 仕様が［ 実装を書するための十分に明瞭な情報 ］を与えていない場合には，そのことについて~bugを申請するべきである。 ◎ Note: Implementers should file bugs against specifications which don’t give them clear enough information to write the implementation.

11.3. 相互運用能と実装-能の対立に対する解決-法

ある特能を指定することには、 すべての~engineering作業と同様に，各種［ ~tradeoffや妥協-法 ］を比較検討することが要求される。 ◎ Specifying a feature, like all engineering work, requires weighing tradeoffs and compromising.

ある特能が，各~実装者~すべてから各自の~engineにおいて実装-可能であると合意されたとしても、 当の特能を相互運用可能に仕様~化する仕方を見出すことに — ~~関係者すべてが最善な労を尽くしても — 失敗するときもある。 ◎ Sometimes, despite the best efforts of all involved, we fail to find a way to interoperably specify a feature that every implementor agrees is implementable in their engine.

進むべき道は、 `末端-利用者にとって何が最良か＠#priority-of-constituencies$に従って選ばれるベキである。 ◎ Choosing a way forward should be guided by what is best for the end user.

まず，実装-能の懸念を成す資質を精査すること。 実装者が，当の特能を実装するベキではないものと — たぶん、 それは末端-利用者にとって害になり得るものと識別した結果 — 裁定した状況においては、 当の特能を仕様~化しないことが — それに伴い、 それを出荷した実装者は，出荷しなくすることが — 最善かもしれない。 特能を出荷しなくすることは、 利用者や作者を惑わす結果を伴い得ることを念頭に置くこと。 ◎ First, examine the nature of the implementability concerns. Perhaps the implementor identified potential end-user harm and decided that the feature should not be implemented. In this situation, it may be best to not specify the feature, and for any implementors who have shipped the feature to un-ship it. Keep in mind that un-shipping features may result in user and author confusion.

同じ~APIが，どの~engineにおいても実装-可能であっても、 その挙動を全部的に相互運用可能にすることは，できないときもある。 各~実装~間で挙動が相違するときは、 末端-利用者への影響iを考慮しなければナラナイ。 この~approachには、 挙動における相違が`特能~検出-可能＠#feature-detect$でなくなる難点がある。 他方，将来において［ すべての実装が同じ挙動に収束することを可能化する ］よう何かを変更した場合でも、 各~siteは，その利点を採るために更新する必要はなくなる。 ◎ Sometimes the same API is implementable in every engine, but its behavior cannot be made to be fully interoperable. Whenever behavior differs between implementations, the end-user impact must be considered. One downside to this approach is that the difference in behavior is not feature detectable. On the other hand, if something changes in the future that enables all implementations to converge on the same behavior, sites will not need to be updated to take advantage of this.

注記： 作者たちは、 支配的な実装の挙動が正しいもので，他の挙動は~bug含みであると見做すようになることもある — それは、 支配的な実装を更に定着させ得る。 ◎ Note: Authors may assume the behavior of the dominant implementation is correct and any other behavior is buggy, which may further entrench the dominant implementaiton.

挙動の相違点が十分に深刻で，それ以上~収束し得ない場合、 異なる~APIを指定して，各~実装者が そのような実装-可能な代替と伴に行く方が好ましいこともある。 ◎ If behavior differences are serious enough, and cannot be converged further, it may be preferable to specify different APIs, with each implementor going with the alternative that they are able to implement.

この~approachには、 次を伴い得る~riskがある ⇒ 実装が最終的に同じ挙動に収束-可能な場合でも， 複数の代替な~APIを不定期に~supportする必要がある結果、 開発者にとって，複階性と実装を保守する~costが増える。 ◎ One risk of this approach comes about if implementations are eventually able to converge on the same behavior. In this case, multiple alternative APIs may need to be supported indefinitely, which can increase developer complexity and implementation maintenance costs.

同じ利用事例に取組むことが意図される 2 つの異なる~APIを公開すると、 作者は，［ `特能~検出＠#feature-detect$を利用して，各~browser用に異なる~codeを書する ］よう強制される。 ◎ Exposing two different APIs that are intended to address the same use cases forces authors to use feature detection to write different code for different browsers.

注記： そこには、 作者たちが［ 支配的な実装が~supportする~API変種を “正しいもの” であると見做すようになる／ 単純に，普段は利用しない実装が~supportする~API変種に~~気付かない ］かもしれない~riskがある — それは、 支配的な実装を更に定着させ得る。 ◎ Note: There is a risk that authors may assume the API variant supported by the dominant implementation is the "correct" one, or they may simply be unaware of the API variants supported in implementations they do not use regularly, which may further entrench the dominant implementaiton.

この道へ行く場合、 各~API~間の相違点を最小~化することにより， 作者の~costを抑制するよう試行すること。 標準でない部分を［ 小さくして，より大きな標準~化された~frameworkから隔離された~componentにする ］よう設計することがアリな場合もあろう。 ◎ If you do go this route, try to reduce the cost to authors by minimizing the differences between the APIs. It may be possible to design things such that the non-standard part is a small, isolated component of a larger, standardized framework.

ある~groupが、 ある~APIを仕様~化することを［ 一部の実装は，それを実装する用意がない ］ことを知りながら，選ぶときもある。 作者は［ 特能~検出を利用して，そのような~APIを可用なときに限り利用する ］ようになり，利用者は［ そのような特能が~supportされ，利用されるときに便益を得られる ］ようになることもあろう。 が、 その結果は，常に問題になり得る — 実装する用意がある実装が 1 つしかないときは、 最悪になる。 一部の標準~化の場には、［ ある特能に関心がある実装が一つしかない場合，その標準~化を許容しない ］とする明示的な規則がある。 そのような~groupに従事していようが、 実装が一つしかない特能を標準~化することは，強く忌避される。 ◎ Groups sometimes choose to specify APIs knowing that some implementations are unwilling to implement it. Authors may use feature detection to only use APIs when they are available, and users may benefit where such features are supported and used. This is always a problematic outcome, though it is worst when there is only one willing implementor. Some standards venues have rules explicitly disallowing the standardization of features which only have a single interested implementor. Even if you are not operating in such a group, standardization of single-implementation features is strongly discouraged.

ある~groupは、 これらの~optionが どれも受容-可能でないことを見出す場合もあろう。 当の特能を仕様~化しないことを選ぶのが最善な道になる場合もあろうが、 一部の実装が当の特能を非-標準な~APIとして出荷し得る~riskもある。 ◎ You may also find that none of these options is acceptable to your group. While the best path forward may be to choose not to specify the feature, there is the risk that some implementations may ship the feature as a nonstandard API.

11.4. ~monkey~patchすることは避けること

`~monkey~patchする@ とは、 既存の仕様の挙動を［ 拡張するか上書きする, あるいは改変する ］仕方で， 既存の仕様の上に新たな機能性の層を重ねることである。 `~monkey~patchすること＠https://en.wikipedia.org/wiki/Monkey_patch$は、 以下に挙げる理由により， `一般に不良な実施であり，避けるベキもの^strongと見なされる — ときには、 避けれないこともあるが （`§ ~monkey~patchする必要がある場合＠#cant-avoid-monkey-patching$の指導を見よ）。 ◎ A monkey patch layers new functionality on top of an existing specification in a way that extends, overrides, or otherwise modifies the existing specification’s behavior. Monkey patching is generally considered bad practice and should be avoided for the reasons listed below; but is sometimes unavoidable (see our guidance if you need to monkey patch).

~monkey~patchする例として、 次が挙げられる ⇒ ある仕様が自身の能力の一部を成す内部的な~algoを定義していて、 別の仕様が公に定義された拡張~地点を利用することなく， 新たな機能性で直に当の~algoを［ 上書きする／改変する ］。 ◎ An example of monkey patching would be: specification A defines an internal algorithm part of its capability, then specification B overrides or modifies said algorithm with functionality directly, not using publicly defined extension points.

そのように~monkey~patchすることは、 当の下層の機能性が決して変更されないものと（間違って）決めつけることに等しい。 これは、 次に挙げる問題に至らせ得る： ◎ As such, monkey patching (wrongly!) presupposes that underlying functionality cannot, and will not, be changed. This can lead to several problems:

• 既存の仕様が変更された場合、 当の~monkey~patchした~textは，もはや適用されなくなり得る — その結果、［ 非互換化する／混同へ至らす ］原因になる。 ◎ If the existing specification changes, the monkey patched text may no longer apply thus causing it to break or lead to confusion.
• いくつかの仕様が別の仕様の一部を~monkey~patchした場合、 それらの~patchが適用された順序により，挙動が一貫しなくなり得る。 【例：どれか一つの~patchしか適用されなくなるなど。】 ◎ If several specifications monkey patch part of another spec, the order in which the patches are applied can lead to inconsistent behavior.
• 既存の仕様の策定者は、 当の仕様~内の~monkey~patchした~textについて自覚しないこともあろう。 その結果、 修正-について総意へ達するための指導を受取る機会も失われる。 さらには、 ~patchされた挙動が他の課題や挙動にも相互に関係している場合，状況は総じて悪化しかねない。 ◎ The existing specification authors may not be aware of the monkey patched text in your spec. This misses an opportunity to receive guidance on reaching consensus on a fix. Or worse, the behavior that is being patched is interrelated to so other issue or behavior, making the overall situation worse.
• ~codeの保守を行っている実装者は，下層の仕様しか読してない結果、 ~monkey~patchされた挙動を~bugと見做して，不作為に元へ復帰することもあろう。 ◎ An implementer doing code maintenance may read underlying specification and inadvertently revert the monkey patched behavior assuming it is a bug.

Wikipedia は、 `~monkey~patchすることによる追加的な陥穽＠https://en.wikipedia.org/wiki/Monkey_patch#Pitfalls$についても述べている。 ◎ Wikipedia also describes some additional pitfalls of monkey patching.

12.1. 共通的な単語を利用すること

~APIは、 容易に可読な米国~英語で命名されなければ`ナラナイ^em 【例： `colour^en （英）ではなく `color^en （米）】。 ほとんどの~web開発者は、 ~nativeな英語~話者でないことを念頭に置くこと。 アリなときは、 名前は，共通的な語彙 — 英語~話者の大多数が，当の名前に最初に遭遇したときでも理解すると見込まれる語彙 — を利用するように選ぶべきである。 ◎ API naming must be done in easily readable US English. Keep in mind that most web developers aren’t native English speakers. Whenever possible, names should be chosen that use common vocabulary a majority of English speakers are likely to understand when first encountering the name.

~~短さより可読性に価値をおくこと。 しかしながら、 名前は短くした方が明瞭になることが多いことを念頭に置くこと。 一例として、 当の仕様~内で当の~APIが定義される所では，［ 専門用語／周知な成句的用語 ］を利用する方が適切になる場合もある。 ◎ Value readability over brevity. Keep in mind, however, that the shorter name is often the clearer one. For instance, it may be appropriate to use technical language or well-known terms of art in the specification where the API is defined.

12.2. ~ASCII名を利用すること

名前は、 当の言語に局所的な制約を固守しなければナラナイ — 例えば，~CSSの `ident$t 規則, 等々。 名前は、 `~ASCII範囲$内にする`べきである^em。 ◎ Names must adhere to the local language restrictions, for example CSS ident rules etc. and should be in the ASCII range.

12.3. 命名-時には他者／他所に諮ること

当の~APIにおける名前を広く諮ること — 思いがけない場所で，良い名前や ひらめきを見出すこともあろう： ◎ Consult widely on names in your APIs. ◎ You may find good names or inspiration in surprising places.

• 他の~platformの類似な~APIや，様々な~programming言語に普及な~libraryでは、 何と命名されているか？ ◎ What are similar APIs named on other platforms, or in popular libraries in various programming languages?
• 当の~APIで［ 作業する／操作する ］ものを何と呼んでいるか，末端-利用者や開発者に訊いてみること。 ◎ Ask end users and developers what they call things that your API works with or manipulates.
• 他の~web~platform仕様を調べて， ~platformに関係する分野で作業している他者からの助言を探求すること。 ◎ Look at other web platform specifications, and seek advice from others working in related areas of the platform.
• 利用される名前は包括的かどうかも諮ること。 ◎ Also, consult if the names used are inclusive.

［ 下層の原則に基づいて明瞭に言明された合理性 ］を伴う助言を受取ったときは、 特に注意を払うこと。 ◎ Pay particular attention to advice you receive with clearly-stated rationale based on underlying principles.

12.4. 将来にも通用する名前を利用すること

アリなときは、 汎用かつ将来にも通用するよう命名するべきである。 ◎ Naming should be generic and future-proof whenever possible.

名前は、 アリなときは，［ 銘柄や下層の技術に特有な改訂 ］に直に結付けられるべきでない — 技術は廃用にされることもある一方で、 ~webから~APIを除去するのは困難なので。 ◎ The name should not be directly associated with a brand or specific revision of the underlying technology whenever possible; technology becomes obsolete, and removing APIs from the web is difficult.

12.5. 一貫するよう命名すること

命名~schemeは、 混同を避けるため，一貫性を目指すべきである。 ◎ Naming schemes should aim for consistency, to avoid confusion.

関係する名前たちが成す集合は、 次について，互いに一致するべきである： ◎ Sets of related names should agree with each other in:

• 品詞 — 名詞, 動詞, 等々。 ◎ part of speech - noun, verb, etc.
• 否定法 — 例えば，集合を成す各~名前は、 次のどちらかにするべきである ⇒＃ すべてが，何が許容されるかを述べる／ すべてが，何が否認されるかを述べる ◎ negation, for example all of the names in a set should either describe what is allowed or they should all describe what is denied

12.6. 危険な特能について警告すること

開発者に供される保証を弱める特能は、 アリな所では — そのことが目立つよう — その名前を【 “安全でない” ことを意味する】 `unsafe^l から開始するようにすること。 ◎ Where possible, mark features that weaken the guarantees provided to developers by making their names start with "unsafe" so that this is more noticeable.

例えば `~CSP＠~CSP3$（ `Content Security Policy^en ）は、 ある種の内容~注入~脆弱性に抗する保護を供する。 ~CSPは、 ~keyword `unsafe-inline^v など，この保証を弱める特能も供する — それは、 ~inline~scriptを許容することにより，~CSPの自前の保護を抑制する。 ◎ For example, Content Security Policy (CSP) provides protection against certain types of content injection vulnerabilities. CSP also provides features that weaken this guarantee, such as the unsafe-inline keyword, which reduces CSP’s own protections by allowing inline scripts.