News for hackers. Stuff that matters.
Re:Strftime's alpha-sorted man page vs. well-meaning people by kazinator on Sunday May 13, 2018 @01:15PM (#17059902)
> 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.

There are no comments on this comment yet.