Skip to content

Commit 50416f9

Browse files
committed
Add Q&A regarding semicolons
1 parent d61bd65 commit 50416f9

1 file changed

Lines changed: 21 additions & 0 deletions

File tree

FAQ.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@
1313
* [What can be done at the standards level to better support numeric computing?](#ecmascript-recommendations)
1414
* [Why reimplement module functionality already available on npm?](#reimplementing-existing-packages)
1515
* [Backward compatibility?](#backward-compatibility)
16+
* [Why use semicolons?](#semicolons)
1617
* [Promise support?](#promise-support)
1718
* [ES2015 and beyond?](#es2015)
1819
* [Why a monorepo?](#monorepo)
@@ -258,6 +259,25 @@ This project has every intent on maintaining backward compatibility with older N
258259
<!-- </faq-question> -->
259260

260261

262+
<!-- <faq-question> -->
263+
264+
---
265+
266+
<a name="semicolons"></a>
267+
268+
### Why use semicolons?
269+
270+
For the following reasons:
271+
272+
1. __Convention__: this project has historically used semicolons and has not found any reason compelling enough to stop doing so.
273+
1. __Explicitness__: this project prefers explicitly terminating statements.
274+
1. __Complexity__: while the [ECMAScript Specification][ecma-262-asi] provides rules governing automatic semicolon insertion ([ASI][ecma-262-asi]), structuring code around these rules increases cognitive overhead and does not provide significant tangible benefit (cumulative keystrokes aside). That workarounds must be employed to prevent [ASI][ecma-262-asi]-enabled errors (e.g., leading semicolons, etc) increases code complexity and imposes an unnecessary cost.
275+
1. __Semantic meaning__: semicolons have semantic meaning within the project REPL. If a statement is not terminated by a semicolon, the REPL prints the statement's return value; otherwise, the REPL considers the statement silent. Such behavior is a common convention in other environments (e.g., MATLAB and Julia) and is especially convenient for silencing output involving large datasets.
276+
1. __Consistency__: given that the project attaches additional meaning to semicolons, that library implementations should be "silent" is also a matter of consistency.
277+
278+
<!-- </faq-question> -->
279+
280+
261281
<!-- <faq-question> -->
262282

263283
---
@@ -512,6 +532,7 @@ See the [contributing guide][contributing-guide].
512532
[ecma-262]: http://www.ecma-international.org/publications/standards/Ecma-262.htm
513533
[ecma-262-array-length]: http://www.ecma-international.org/ecma-262/6.0/#sec-arraycreate
514534
[ecma-262-tolength]: http://www.ecma-international.org/ecma-262/6.0/#sec-tolength
535+
[ecma-262-asi]: https://www.ecma-international.org/ecma-262/5.1/#sec-7.9
515536

516537
[golang-frexp]: https://github.com/golang/go/blob/c007ce824d9a4fccb148f9204e04c23ed2984b71/src/math/frexp.go#L27
517538
[golang-float64bits]: https://github.com/golang/go/blob/964639cc338db650ccadeafb7424bc8ebb2c0f6c/src/math/unsafe.go#L17

0 commit comments

Comments
 (0)