Skip to content

Commit 6494c50

Browse files
committed
docs/style: "URL" is the standard term, not "URI"
1 parent 8a4703c commit 6494c50

File tree

1 file changed

+30
-0
lines changed

1 file changed

+30
-0
lines changed

docs/style.md

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,8 @@
2727
* [[link](#catch-at-ui)] For exceptions that aren't bugs, catch them
2828
in UI code and inform the user.
2929
* [[link](#catch-specific)] Only catch specific, expected exceptions.
30+
* [Naming](#naming)
31+
* [[link](#url-not-uri)] "URL" is the standard term, not "URI"
3032
* [JavaScript, Flow, JS libraries](#js)
3133
* [[link](#types-named-type)] Don't put "type" in the name of a
3234
type, usually.
@@ -416,6 +418,34 @@ Discussion elsewhere:
416418
[Effective Dart](https://dart.dev/guides/language/effective-dart/usage#error-handling)
417419

418420

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+
419449
<div id="js" />
420450

421451
## JavaScript, Flow, JS libraries

0 commit comments

Comments
 (0)