Skip to content

Commit beaaef9

Browse files
Clarify the strings for enums/constants principle (#555)
Adds examples and tightens things up. Adds a mention that WebIDL enums only take string values. Closes #427. Co-authored-by: Jeffrey Yasskin <[email protected]>
1 parent af2965b commit beaaef9

File tree

1 file changed

+19
-5
lines changed

1 file changed

+19
-5
lines changed

index.bs

+19-5
Original file line numberDiff line numberDiff line change
@@ -1996,18 +1996,32 @@ is a request, rather than a guarantee.
19961996

19971997
<h3 id="string-constants">Use strings for constants and enums</h3>
19981998

1999-
If your API needs a constant, or a set of enumerated values,
2000-
use string values.
1999+
Use strings as the values for constants or sets of enumerated values.
20012000

2002-
Strings are easier for developers to inspect,
2003-
and in JavaScript engines there is no performance benefit
2004-
from using integers instead of strings.
2001+
Strings make it easier for developers to inspect values
2002+
and read code that uses those values.
2003+
In JavaScript engines there is no performance benefit
2004+
to using integers instead of strings.
2005+
The values of a [WebIDL enum type](https://webidl.spec.whatwg.org/#idl-enums)
2006+
are strings in order to follow this principle.
20052007

20062008
If you need to express a state which is a combination of properties,
20072009
which might be expressed as a bitmask in another language,
20082010
use a dictionary object instead.
20092011
This object can be passed around as easily as a single bitmask value.
20102012

2013+
<div class=example>
2014+
The type of a dedicated Worker is set using an enumerated {{WorkerType}} argument.
2015+
This has two values ("classic" and "module") and might have used a Boolean type instead.
2016+
The use of strings costs nothing and makes code clearer.
2017+
</div>
2018+
2019+
<div class=example>
2020+
The {{XMLHttpRequest}} {{XMLHttpRequest/readyState}} getter returns an enumerated integer value.
2021+
Code that uses this API therefore requires that readers are familiar with the API to understand it.
2022+
</div>
2023+
2024+
20112025
<h3 id="async-by-default">If you need both asynchronous and synchronous methods, synchronous is the exception</h3>
20122026

20132027
In the rare case

0 commit comments

Comments
 (0)