10 ms·
Strftime's alpha-sorted man page vs. well-meaning people
- fanf2 9y agoThe irony of this bug is that immediately above %G is %F (short for %Y-%m-%d) which is they wanted...
- corrigible 9y agoSo, people don't always pay attention to what they're reading?... strftime(3) says[0]: "This has the same format and value as %Y, except that if the ISO week number belongs to the previous or next year, that year is used instead. (TZ (Calculated from tm_year, tm_yday, and tm_wday.)" [0]: http://man7.org/linux/man-pages/man3/strftime.3.html http://man7.org/linux/man-pages/man3/strftime.3.html
- paultopia 9y agoThe problem is that this text makes no sense standing alone... why would anyone imagine that a week number might belong to a year other than the year it's in without a separate detailed explanation?
- gkya 9y agoBecause not every year starts on monday?
- twic 9y agoI agree that most people, on reading it, wouldn't understand exactly what it meant. But i think an adequately sharp person would think "i don't understand exactly what that means, so i'm going to find out before i use it". A person whose response is "i don't understand exactly what that means, but it sounds close, so i'm going to use it" should probably not be doing detail work like programming.
- samatman 9y ago> This has the same format and value as %Y When I see a line like that, I check %Y immediately. Unless I'm tired, in a hurry, or just not paying enough attention.
- gpvos 9y ago...which happens to many people once in a while...
- deleted 9y ago[deleted]
- kazinator 9y agoThe text makes it clear that the week can belong to another year. This piece of documentation leaks numerous clues that it's describing something radioactive that you want to stay away from And it gives away the specifier that you want: %Y. "Same format as %Y except ..." means "this is some extended/twisted version of another year format, which is assigned to the obvious %Y letter. Hmm, maybe I should check that one out!"
- craigds 9y agoWhat on earth is %G even for? In what situation would that _ever_ be useful?
- gpvos 9y agoWhen you're working with ISO week numbers, and you want to know the year that the week belongs to. Lots of companies do that, for example for work schedules in all kinds of industries.
- hyperman1 9y agoYou should never use it in a day-month-year situation, but it is very useful in a weekofyear-year situation commonly encountered in bookkeeping. You have to decide what to do with the week that gets broken up when a new year starts, and the ISO standard makes sure everybody uses the same week numbers. I personally experienced how this mattered when someone in our company was unaware of ISO and decided to invent an other week schema as new standard. First came the people who complained outlook numbered them differently. Then the complaints that all other companies delivered using another system. Then it turns out data transfers from the government didn't match either. Finally one guy pops up and sends the link to ISO in wikipedia. Our whole 1000 man part of the org was in CC of the original mail, and naturally we received all reply complaints too. After a very noisy few days in the inbox, all of us knew all about ISO weeks and why they matter. Training couldn't be better.
- masklinn 9y agoSome processes work by week, so you want week-year dating, and you may in fact want ISO week-years rather than "calendar".
- brohee 9y agoIt's what numbers week in calendars... I don't like numbered weeks much myself but some people are absolutely in love with it...
- EdSchouten 9y agoThere are many companies out there that work with weekly schedules (e.g., in production). In some of those cases you're not necessarily interested in using months and days of the month. Instead, you want to use week numbers. These flags are part of strftime(), so you can generate ISO 8601 week-based dates: strftime(..., "%G-W%V-%u", ...) This will generate output along the lines of "2018-W19-7"
- speedplane 9y agoSo many frameworks try to be smart about timzones and user settings. Showing local time to users is fine, but please don't touch my UTC time that's actually stored in the dbase.
- kbob 9y ago"RTFM" used to be a valid critique, and it's my immediate response to this article. But maybe I'm wrong. The M keeps getting bigger, and our reading time keeps getting more fractured. Maybe it's okay to just throw code out without knowing what it does. Or maybe management/engineering culture need to be clear on the external costs of slapdash development and discourage breaking things fast.
- DougBTX 9y ago> Maybe it's okay to just throw code out without knowing what it does. I think at time pressure increases, the grey area between right and wrong grows. Here the hypothetical user did read the fine manual, and they thought they knew what the code did, and when they ran it, the output was what they expected. Really they did everything correctly, except for the fact that they were wrong. This article is addressing the next level up from RTFM. Given a dev that is reading the manual, how can it be optimised such that they can learn to use the tool correctly? How can project standards be defined so that eg, fiddly date formatting code doesn’t need to be repeated?
- xtrapolate 9y ago> "But maybe I'm wrong." I don't think you are wrong. Timing APIs are tricky and complicated. The small print really matters. Experienced engineers will know this, and so the answer in this instance, as annoying as it may be - absolutely RTFM. Also, funky documentation/APIs exist everywhere, unfortunately. Quoting the article: > "You're a new coder, and you find yourself tasked with taking a Unix time_t type value and turning it into some kind of human-readable format" I'd argue that's exactly the kind of mistakes inexperienced coders are prone to make. Hence we have code-reviews.
- ygra 9y agoI think the problem in such situations is that the M needs to address two different use cases: 1. Reference for what exists. This is used by people who don't know what %Ð is a placeholder for. Alphabetic sorting has a big advantage here. 2. Manual for what can be done. This should arguably be grouped differently, e.g. Full dates, years, months, days, etc. since there are often several placeholders for each category that are otherwise pretty far apart at times.
- hyperman1 9y agoShe raises a very valid criticism. The Java SimpleDateFormat has a similar gotcha concerning %k vs %h ('What do you mean, my program only works in the morning'?) I don't think her solution is right, however: A better fix is to get people away from using format strings altogether. What do you propose instead? have one person get it right, [...] then ban all other attempts to use the strings directly Thats basically part of an in-house library for something simple. In my experience, contractors either flat-out refuse to use it ('reinventing the square wheel, har har har'), or don't read the docs and rewrite it using the API. Then they extract common code from their application together with some half-baked framework, declare it a new in-house library. so when the next contractor comes, he has one more reason to ignore the well thought out library. In-house libraries work fine for complex problems, but large collections of small utilities get rewritten by everyone. No. Learn the details of your programming language, libraries and frameworks. Even their gotchas. Read blogs, listen to coworkers, learn the idioms. As a result, you don't store this knowledge in your current corner of some random company. You store it in the ecosystem of the language. It will influence future languages, and slowly the gotchas either disappear or become an near-universal standards. And I guess that's exactly what this blog post helped to accomplish. Thanks, Rachel ;-)
- michaelt 9y agoWhat do you propose instead? Java provides a set of predefined date formatters in the standard library [1] - like 'ISO_LOCAL_DATE_TIME' and 'RFC_1123_DATE_TIME' Of course, they don't cover every possibility - if you want milliseconds, you've got to roll your own :) [1] https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html https://docs.oracle.com/javase/8/docs/api/java/time/format/D...
- hyperman1 9y agoVery true. Another example is the jquey UI date picker which stores nice defaults in the i18n files. I would classify these as storing the knowledge in the ecosystem.
- bobbyi_settv 9y ago
- alanbernstein 9y agoI think the real lesson here is "don't use man pages". Seriously, that's often my last resort.
- true_religion 9y agoInterestingly enough, I've never heard of %G or the ISO Week. I thought I was familiar with the ups and downs of strftime but I've mostly used it through Python and the Python reference helpfully neglects to mention %G or any tricksy parameters that you may get confused by. https://docs.python.org/2/library/time.html https://docs.python.org/2/library/time.html
- jwilk 9y ago> Additional directives may be supported on certain platforms, but only the ones listed here have a meaning standardized by ANSI C %G was added only in C99.
- paultopia 9y agoThat gotcha was added? Woah. I was thinking it must have been some legacy thing that hasn't gotten removed because there's code from, like, the dark ages buried in the drivers and such that depends on it.
- gkya 9y agoIt was probably useful to someone else. I don't get why it should be a gotcha. Libraries can not be optimized for individuals and features that one does not use are not gotchas.
- jwilk 9y agoTimezone abbreviations (like PDT) are neither human- nor machine-readable. Avoid them.
- rocqua 9y agoHow to represent the CEST timezone then? Writing "Central European Summer Time" in full is very big, but UTC+2:00 is actually something else than CEST. I think standard abbreviations are a nice middle ground, at least when a time-zone is needed. Otherwise, just report stuff in UTC.
- chrismorgan 9y ago> UTC+2:00 is actually something else than CEST I presume you’re referring to the fact that CEST is +0200, but +0200 is not necessarily CEST?
- gpvos 9y ago+0200 suggests it's +0200 all year long. CEST means you've configured something like the Europe/Brussels time zone and the time mentioned falls in the summer period.
- rocqua 9y agoConsider the time 24 hours after summer time ends? Then you probably want to consider you need to switch time-zones in your display.
- andrewaylett 9y agoYou should probably use the time zone identifier from the IANA list, which would be 'Europe/Paris' or similar. https://www.iana.org/time-zones https://www.iana.org/time-zones Accessible copy here: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
- hyperman1 9y ago
- oherrala 9y agoThere are 7458 hits for simple code search for "%G-%m-%d" on GitHub: https://github.com/search?q=%22%25G-%25m-%25d%22&type=Code https://github.com/search?q=%22%25G-%25m-%25d%22&type=Code Plenty of code to go through and fix.
- EdiX 9y agoAlmost all of them are from the documentation of flysystem which is some kind of PHP abstraction layer for filesystems.
- TomK32 9y agoNot for much longer I hope https://github.com/thephpleague/flysystem/pull/927 https://github.com/thephpleague/flysystem/pull/927
- TomK32 9y agoI was about to pick my language and work through them, but alas ruby's strftime doc turns out to be better than other languages :)
- TomK32 9y agoHaha, this is a funny one https://github.com/jolantis/vanwunnik/blob/aff30c8d984b7cb65587fbfa37201c825127f65b/site/snippets/datetime.php#L12 https://github.com/jolantis/vanwunnik/blob/aff30c8d984b7cb65...
- kazinator 9y agoThe issue raised in this article is extremely tenuous. The "Linux Programmer's Manual" man page from the Linux documentation project has it as: %G The ISO 8601 week-based year (see NOTES) with century as a deci‐ mal number. The 4-digit year corresponding to the ISO week num‐ ber (see %V). This has the same format and value as %Y, except that if the ISO week number belongs to the previous or next year, that year is used instead. (TZ) This clearly says "%G is some ISO nonsense you don't want to be using". But the "week-based year" alone should alert you that something is wrong. Because, like, the year that you know is not week-based! There aren't exactly 52 weeks in a year: 365 isn't divisible by 7, and if it were, then 366 wouldn't be. A (see NOTES) is also alarming. Why do you have to see some notes about planting the year part of the date into a simple date string? The glibc manual has it here:https://www.gnu.org/software/libc/manual/html_node/Formatting-Calendar-Time.html#Formatting-Calendar-Time https://www.gnu.org/software/libc/manual/html_node/Formattin... It also makes it perfectly clear that this is something weird: "This has the same format and value as %y, except that if the ISO week number (see %V) belongs to the previous or next year, that year is used instead. This format was first standardized by ISO C99 and by POSIX.1-2001." Three warning labels here: ISO, C99 and POSIX 2001! C99 itself gives it like this. %G is replaced by the week-based year (see below) as a decimal number (e.g., 1997). [tm_year, tm_wday, tm_yday] If you don't "see below", that is your problem, just like ignoring "(see NOTES)". The "see below" paragraph has this: %g, %G, and %V give values according to the ISO 8601 week-based year. In this system, weeks begin on a Monday and week 1 of the year is the week that includes January 4th, which is also the week that includes the first Thursday of the year, and is also the first week that contains at least four days in the year. [... more explanation]
- wffurr 9y agoThose 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.
- yason 9y agoWell. Programming, like life in general, is made out of imperfections. There is a shitload of corner-cases in APIs both ancient and modern that you cannot possibly "fix for all" or, alternatively, learn to avoid. In many cases, it suffices to take that %G after a cursory glance, bump into some weird non-continuous dates later, read the man page again in the heat of a WTF, and change it to %F. There are applications and cases where dates, and especially the exactness, correctness, and coherency of dates, is of some hugely important factor. Software for banking, accounting, train scheduling, or flying come to mind. In these cases the standard library behaviour can be tested for expected values, or rather, a custom and audited library be written by the team. But for the majority of programs, things like little glitches in dates, compatibility of encoding conventions in file names and paths, floating point numbers used as decimals etc. will be of little significance. It takes a lot of these to align to unlock one big disaster, and while it is good to strive for perfection there's always a cost to all the little things. If the failures are manageable it is often more practical to just wait for those that will eventually happen.
- jcims 9y agoIsn't part of the problem the fact that it's a pain in the ass to write unit tests for system time?
- xfitm3 9y agoI generally support efforts to reduce human error, but the author goes too far by calling for format strings to be abolished. Localization is hard, which is why these functions exist. There is ctime() but it includes a trailing \n which isn’t always what you want.
- masklinn 9y ago> There is ctime() but it includes a trailing \n which isn’t always what you want. It's also not useful what with being in a hard-coded US customary format.
- NelsonMinar 9y agoThis exact feature trap killed Twitter Android severla years ago: https://www.theguardian.com/technology/2014/dec/29/twitter-2015-date-bug https://www.theguardian.com/technology/2014/dec/29/twitter-2...
- karmakaze 9y agoHow about using a collation sequence like aAbBcC...? then many of the misused flags are near the intended ones.
- zorkw4rg 9y agoyou might call this a gotcha of this obscure standard called UNIX/POSIX, although... > %G The ISO 8601 week-based year (see NOTES) with century as a decimal number. The 4-digit year corresponding to the ISO week number (see %V). This has the same format and value as %Y, except that if the ISO week number belongs to the previous or next year, that year is used instead. (TZ) I think that's pretty clear, so its actually just a case of not reading / bothering to understand the documentation. I think if you really want to bulletproof a system against incompetency we should probably not start with C.
- kazinator 9y agoI don't think Rachel is incompetent. She had a brain-slip and is trying to blame it on some external factors. "I can't explain why I didn't understand this simple, clear piece of documentation. But, aha, if the sections weren't sorted such that it came first before the common thing I was looking for, this wouldn't have happened." It's just grasping at straws. There is no way for a documentation writer to predict who will have a momentary brain lapse, reading what passage. Putting something more toward the back of the document isn't a guarantee that someone won't trip up on it.
- rachelbythebay 9y agoIt was never about me. I didn’t make this error. I did, however, fix it and added steps to make it not happen again.
- emilfihlman 9y agoThis is not valid criticism at all. This is just your programmer a) being lazy and not reading the manual (which is short) and b) not writing tests.
- userbinator 9y agoDo you really want all of your programmers learning this lesson? IMHO yes, because if they don't pay attention to such things, they're going to make even more subtle mistakes in the future. Besides the explicit mention to "see NOTES", the fact that most of the format specifiers are mnemonic for the common parts, like H M and S for Hour, Minute, and Second, should be enough to arouse some suspicion when you see G being used for "Year". They weren't assigned arbitrarily --- with the most mnemonic ones being assigned first --- and presumably, people wanted to print years very early in its history, so your next thought should be "then what did they use Y or y for?" If you're really observant, noticing that months and days are lowercase, you may also ask "what's g?" That will naturally lead you to the right choice. My point is, there's a pattern to these things, and the instinct to ask "why?" and find out when something doesn't feel "right" is very important. More abstractly, "reading requires thinking".
- _vertigo 9y agoI don’t think that man pages being oriented in a more user friendly manner will lead to programmers making mistakes in subtler areas. You’re basically saying that programming even basic things should be hard so that people learn to be thorough, but I think that people will have less time to be thorough on the hard parts of programming if 1) even the easy parts require navigating a needlessly complex mass of documentation and 2) programmers have to spend time fixing all of the bugs caused each week by needlessly complex documentation.
- userbinator 9y agoI'm saying that the strftime() format specifiers for "basic things" are not hard, since they're mnemonics, and anyone who doesn't find it the least bit unusual to use %G instead of %Y when trying to print a year is not paying attention. I do not think the documentation is "needlessly complex". In fact, I just asked someone who doesn't know programming at all, after giving her "%m %d %H %M %S" and saying it was a way of formatting a date, to guess how to add a year in front. She guessed... %y. That's actually the two-digit year, which is close enough --- the point is she didn't say %G or some other letter. I'd almost be willing to bet that if you repeated this exercise with many other non-programmers, you'd find the same result. Then, why would someone be perfectly fine with using %G? To rebut the first sentence of the article, "I have another tale of humans being humans, and getting into trouble when using computer systems", this is not "humans being humans"; it's closer to the "intelligent human losing all semblance of critical thought when put in front of a computer" phenomenon, which certainly deserves further investigation.
- kazinator 9y agoThe compiler could help here. It makes sense for %G to appear with %V, but not with %m and %d. Nonsensical combinations like this can be diagnosed with a compiler warning if the strftime format is a string literal directly passed to strftime, or found to do so via data flow. A run-time warning would be nice, but problematic.
- TomK32 9y agoHere's how the formats should be listed and grouped: https://apidock.com/ruby/DateTime/strftime https://apidock.com/ruby/DateTime/strftime