-
Notifications
You must be signed in to change notification settings - Fork 29.6k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
doc: consolidate use of multiple-byte units #42587
Conversation
Review requested:
|
Similar: #35051 |
I may be behind the times on what abbreviations we can expect people to be familiar with, but I think this is going to confuse people more than enlighten them. Also FWIW the style guide doesn't seem to recommend this. https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/bits-bytes-terms |
That's likely true. For memory sizes, for example, GB almost exclusively means base 2 anyway, whereas things are vastly different for data transmissions etc. |
I agree. Anyway, this PR LGTM if we want to use those units. |
I'm further confused by people both approving this PR and agreeing that it is likely to increase confusion. |
Lol. You are definitely right. I meant to say that the code changes look fine and we could definitely land this to improve docs(up for me on this). But, at the same time, the possible confusion is definitely worth a second evaluation (in contrast to handle this like a trivial doc fix PR). Hope this rant was understandable :) |
My take on this is we should use the technically correct units in our code and comments, I think it's fair to assume that most folks who would read it would not be confused by them. |
The standard that defined KiB as the abbreviation for 1024 bytes also says that the unit is a kibibyte and not a kilobyte (which is 1000 bytes, according to the standard). I don't think any of this is at all widely adopted and I'm not sure I want Node.js docs to be an early adopter for this type of thing, especially when "early adopter" means doing it after 15 years of no significant adoption of the terms. This from 2009 still seems to be the case: [Why does Explorer use the term KB instead of KiB?}(https://devblogs.microsoft.com/oldnewthing/20090611-00/?p=17933):
|
I don't love it, but it does have the virtue of precision. Another option is to always use bytes: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
lgtm
(All my cranky comments are non-blocking. I just want these things considered before we land.) |
I'm further confused by people both approving this PR and agreeing that it is likely to increase confusion.
I'm all for favoring correctness where it matters, and especially in scientific writing, I try to consistently use IEC symbols (KiB, MiB, etc.). That being said, according to the reference @aduh95 provided, using the unit symbols KB, MB, etc. for base-2 units is not incorrect but merely legacy: |
Another possibility (that might not always be practical) would be to use the common/"legacy" abbreviations but precise byte counts for clarity: |
I like this one. |
Given that this PR has enough approvals + wait time, I'm down to land it as it, and to improve on follow up PRs. FWIW I'd be disappointed if we had to settle on using the legacy units, but as long as we remove the confusion of when we're using metric and when we're using base-2, I'm fine with it. |
Landed in 1e76165 |
Refs: https://en.wikipedia.org/wiki/Byte#Multiple-byte_units PR-URL: nodejs#42587 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Darshan Sen <raisinten@gmail.com> Reviewed-By: Paolo Insogna <paolo@cowtech.it> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Mestery <mestery@protonmail.com>
Refs: https://en.wikipedia.org/wiki/Byte#Multiple-byte_units PR-URL: #42587 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Darshan Sen <raisinten@gmail.com> Reviewed-By: Paolo Insogna <paolo@cowtech.it> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Mestery <mestery@protonmail.com>
Refs: https://en.wikipedia.org/wiki/Byte#Multiple-byte_units PR-URL: #42587 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Darshan Sen <raisinten@gmail.com> Reviewed-By: Paolo Insogna <paolo@cowtech.it> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Mestery <mestery@protonmail.com>
Refs: https://en.wikipedia.org/wiki/Byte#Multiple-byte_units PR-URL: #42587 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Darshan Sen <raisinten@gmail.com> Reviewed-By: Paolo Insogna <paolo@cowtech.it> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Mestery <mestery@protonmail.com>
Refs: https://en.wikipedia.org/wiki/Byte#Multiple-byte_units PR-URL: #42587 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Darshan Sen <raisinten@gmail.com> Reviewed-By: Paolo Insogna <paolo@cowtech.it> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Mestery <mestery@protonmail.com>
Refs: https://en.wikipedia.org/wiki/Byte#Multiple-byte_units PR-URL: #42587 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Darshan Sen <raisinten@gmail.com> Reviewed-By: Paolo Insogna <paolo@cowtech.it> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Mestery <mestery@protonmail.com>
Refs: https://en.wikipedia.org/wiki/Byte#Multiple-byte_units PR-URL: nodejs/node#42587 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Darshan Sen <raisinten@gmail.com> Reviewed-By: Paolo Insogna <paolo@cowtech.it> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Mestery <mestery@protonmail.com>
Refs: https://en.wikipedia.org/wiki/Byte#Multiple-byte_units