3 ms·

Those are not obvious "warning labels". Standards usually sound like a good thing. Both comments bury the lede. The bit that alludes to but does not actually

by wffurr 8y ago

Those are not obvious "warning labels". Standards usually sound like a good thing. Both comments bury the lede. The bit that alludes to but does not actually state "this does not do what you want" is at the end of the description, not the beginning where it might actually warn someone off. "You didn't read and understand the whole documentation for this complex feature" is not making it easy to do the right thing. It's just fodder for people "in the know" to make fun of normies.

kazinator 8y ago
> You didn't read and understand the whole documentation for this complex feature Formatting a year's date into a string doesn't require a complex feature; the "complex feature" part is a warning itself. The date object (struct tm) has a year field that is a simple integer (almost: it's years since 1900). Sticking that into a string in the format "2018" is trivial. The word "weeks" doesn't enter into it and we don't need ISO to figure it out. Also, you have to be super naive to believe that G was used for "year" instead of the letter Y, and then not even wonder out of curiosity that, if this is how you're supposed to obtain the year, why Y was not available and what the heck Y is being used for. The software field requires people who are curious like this and read documentation critically (as they do code). Why would someone invent a date formatting printf thing in which %H is hour, but year is %G? Why would they forget to add the year feature, then use Y for something else, and add year support under G in some new standard? Of course, any nonsense lettering is due to historic extension when letters are running out. Why would the basic feature of generating year part of a date string be a historic extension? > Standards usually sound like a good thing. The first standard for a programming language or API is often good; then it is usually severely screwed in subsequent revisions. This is massively evident in C, C++, POSIX, Unicode, WWW, IP, USB, Ethernet, ...
- wffurr 8y ago
  The whole point, which you are missing, is to make the API simple and obvious for a naive reader, which is most of us. Not everyone is as immersed in Unix and C culture as you clearly are.
  - deleted 8y ago
    [deleted]
  - kazinator 8y ago
    > make the API simple and obvious Note that make the API is a very distinct activity from document the API, which is what is being criticized here. A better API would use long identifiers for all weird stuff like %{iso-week-based-year} instead of %G. > Unix and C culture I'm confident I could properly understand an above-par engineering document written in plain English, such as what is being criticized here, from any branch of computing. You can't pin this on Unix and C culture. Those man pages are documenting this weird ISO "week-based year" about as well as can be. If you read documents in such a manner that you drop random adjectives (such that "week-based year" looks like "year" to your eyes) and ignore anything in parentheses as being optional such as "(see ...)" notices, that's a comprehension problem. If the descriptions were not sorted alphabetically, that would also be criticized as unfriendly. Users would have to exhaustively scan that section when trying to decipher a format string that someone else wrote.

by wffurr 8y ago

kazinator 8y ago

> You didn't read and understand the whole documentation for this complex feature Formatting a year's date into a string doesn't require a complex feature; the "complex feature" part is a warning itself. The date object (struct tm) has a year field that is a simple integer (almost: it's years since 1900). Sticking that into a string in the format "2018" is trivial. The word "weeks" doesn't enter into it and we don't need ISO to figure it out. Also, you have to be super naive to believe that G was used for "year" instead of the letter Y, and then not even wonder out of curiosity that, if this is how you're supposed to obtain the year, why Y was not available and what the heck Y is being used for. The software field requires people who are curious like this and read documentation critically (as they do code). Why would someone invent a date formatting printf thing in which %H is hour, but year is %G? Why would they forget to add the year feature, then use Y for something else, and add year support under G in some new standard? Of course, any nonsense lettering is due to historic extension when letters are running out. Why would the basic feature of generating year part of a date string be a historic extension? > Standards usually sound like a good thing. The first standard for a programming language or API is often good; then it is usually severely screwed in subsequent revisions. This is massively evident in C, C++, POSIX, Unicode, WWW, IP, USB, Ethernet, ...

wffurr 8y ago
The whole point, which you are missing, is to make the API simple and obvious for a naive reader, which is most of us. Not everyone is as immersed in Unix and C culture as you clearly are.
- deleted 8y ago
  [deleted]
- kazinator 8y ago
  > make the API simple and obvious Note that make the API is a very distinct activity from document the API, which is what is being criticized here. A better API would use long identifiers for all weird stuff like %{iso-week-based-year} instead of %G. > Unix and C culture I'm confident I could properly understand an above-par engineering document written in plain English, such as what is being criticized here, from any branch of computing. You can't pin this on Unix and C culture. Those man pages are documenting this weird ISO "week-based year" about as well as can be. If you read documents in such a manner that you drop random adjectives (such that "week-based year" looks like "year" to your eyes) and ignore anything in parentheses as being optional such as "(see ...)" notices, that's a comprehension problem. If the descriptions were not sorted alphabetically, that would also be criticized as unfriendly. Users would have to exhaustively scan that section when trying to decipher a format string that someone else wrote.