|
27 | 27 | * [[link](#catch-at-ui)] For exceptions that aren't bugs, catch them
|
28 | 28 | in UI code and inform the user.
|
29 | 29 | * [[link](#catch-specific)] Only catch specific, expected exceptions.
|
| 30 | +* [Naming](#naming) |
| 31 | + * [[link](#url-not-uri)] "URL" is the standard term, not "URI" |
30 | 32 | * [JavaScript, Flow, JS libraries](#js)
|
31 | 33 | * [[link](#types-named-type)] Don't put "type" in the name of a
|
32 | 34 | type, usually.
|
@@ -416,6 +418,34 @@ Discussion elsewhere:
|
416 | 418 | [Effective Dart](https://dart.dev/guides/language/effective-dart/usage#error-handling)
|
417 | 419 |
|
418 | 420 |
|
| 421 | +<div id="naming" /> |
| 422 | + |
| 423 | +## Naming |
| 424 | + |
| 425 | +<div id="url-not-uri" /> |
| 426 | + |
| 427 | +**"URL" is the standard term, not "URI"**: |
| 428 | +Use the term "URL", never "URI", wherever possible. The one situation |
| 429 | +in which we use "URI" is in names that come directly from an external |
| 430 | +API. |
| 431 | + |
| 432 | +This applies to jsdoc, comments, user-facing text, and all names |
| 433 | +internal to our codebase. |
| 434 | + |
| 435 | +The term "URI" has been explicitly deprecated |
| 436 | +[by web standards][url-spec-goals] since the early 2010s. |
| 437 | +[In older standards][url-not-uri-thread] it was the officially |
| 438 | +preferred term, which is why some older APIs use it, but it was never |
| 439 | +nearly as widely [adopted][url-not-uri-history-discussion] as "URL". |
| 440 | +Consistently saying "URL" is therefore the most standard usage in both |
| 441 | +senses: it's prescribed by the relevant standard, and it's the most |
| 442 | +common usage and therefore minimizes the confusion of multiple terms. |
| 443 | + |
| 444 | +[url-not-uri-thread]: https://chat.zulip.org/#narrow/stream/92-learning/topic/URLs/near/794826 |
| 445 | +[url-spec-goals]: https://url.spec.whatwg.org/#goals |
| 446 | +[url-not-uri-history-discussion]: https://github.com/zulip/zulip-mobile/pull/4124#discussion_r431542224 |
| 447 | + |
| 448 | + |
419 | 449 | <div id="js" />
|
420 | 450 |
|
421 | 451 | ## JavaScript, Flow, JS libraries
|
|
0 commit comments