diff --git a/index.bs b/index.bs index 918b1839..6224fb9e 100644 --- a/index.bs +++ b/index.bs @@ -2784,7 +2784,7 @@ As more specific information is shared, the [fingerprinting data](https://www.w3.org/TR/fingerprinting-guidance/) available to sites gets larger. -There are also [other potential risks]([[PRIVACY-PRINCIPLES#threats]]) +There are also [[PRIVACY-PRINCIPLES#threats|other potential risks]] to user privacy. If there is no way to design a less powerful API, @@ -3634,7 +3634,7 @@ Names take meaning from: * use (how people come to understand the name over time) * context (the object on the left-hand side, for example) -

Use common words

+

Use common words

API naming *must* be done in easily readable US English. Keep in mind that most web developers aren't native English speakers. @@ -3668,12 +3668,12 @@ to name this API less directly connected to its return type. [[FETCH]] -

Use ASCII names

+

Use ASCII names

Names must adhere to the local language restrictions, for example CSS ident rules etc. and *should* be in the [=ascii code point|ASCII range=]. -

Consult others on naming

+

Consult others on naming

Consult widely on names in your APIs. @@ -3728,7 +3728,7 @@ such as an author or user, use the generic pronoun "they", "their", etc. For example, "A user may wish to adjust their preferences". -

Use future-proof names

+

Use future-proof names

Naming should be generic and future-proof whenever possible. @@ -3755,7 +3755,7 @@ as they were to PS/2 and ADB keyboards back then. [[UIEVENTS]] -

Name things consistently

+

Name things consistently

Naming schemes should aim for consistency, to avoid confusion. Sets of related names should agree with each other in: @@ -3764,14 +3764,14 @@ Sets of related names should agree with each other in: or they should all describe what is denied

Boolean properties vs. - boolean-returning methods

+ boolean-returning methods Boolean properties, options, or API arguments which are asking a question about their argument *should not* be prefixed with is, while methods that serve the same purpose, given that it has no side effects, *should* be prefixed with is to be consistent with the rest of the platform. -

Use casing rules consistent with existing APIs

+

Use casing rules consistent with existing APIs

Although they haven't always been uniformly followed, through the history of web platform API design, the following rules have emerged: @@ -3824,8 +3824,8 @@ design, the following rules have emerged: Events Lowercase, concatenated - {{canplaythrough}}
- {{languagechange}} + {{canplaythrough}}
+ {{languagechange}} HTML elements and attributes @@ -3886,7 +3886,7 @@ existing factory methods under the same object, such as `document.initXXX()`. New factory methods should not follow this convention. -

Warn about dangerous features

+

Warn about dangerous features

Where possible, mark features that weaken the guarantees provided to developers