Re: Decoded time accessors

[Alan Mackenzie]

Hello, Lars.

On Sun, Jul 07, 2019 at 21:33:19 +0200, Lars Ingebrigtsen wrote:
> A while back we added accessors to the return value from
> `file-attributes' (i.e., `file-attribute-size' etc), and I think that
> was a readability win.

I disagree strongly.  It may be a "readability" win, but comes at great
cost.

My limited experience of this is that people don't bother to write the
necessary doc strings, or don't bother to write them properly, so one is
left guessing at the precise semantics.  For example the doc string for
`file-attribute-size' is poor, whereas the doc string for
`file-attribute' is better, though still not perfect.  To understand the
former, one must read _both_ doc strings.  This is not a win.

> I think we should do the same for the return value for `decode-time',
> but do it as settable values instead:

I disagree.  All these "readability hacks" greatly increase the number
of functions a hacker must cope with, and greatly increase their
complexity (they require cl-... macros, many of which are poorly
documented).

We've coped now with (nth 8 state) (for the starting position of a
string or comment) for decades now without any problems.  The sort of
"readability hack" proposed, as it is steadily proliferated, makes the
entry barrier for new Elisp programmers steadily higher.  To use it is
one extra thing which has to be learned, or looked up.

Are all these accessors going to find their way into the index of the
Elisp manual?  Well, yes, they need to.  But this will bloat that index
uncontrollably.

Personally, I find it rather un-lispy, more like C++.
(decoded-time-year result) looks like a (complicated) function call,
which you need to look up to find out what it does.  How is one, at a
glance, to tell whether that form is just an accessor, or a true
function call?  On the other hand (nth 5 result) is chrystal clear,
except to the rawest of beginners.

The other day, I came across new interfaces involving mark-data.  Rather
than return a simple 3-element list, they construct a (basically
undocumented) 3 element type, with accessors.  Why?  Because the fancy
cl- macro is there, therefore should be used?  Because the short
expression (nth 1 result) is too easy, and needs to be made more
complicated?  Because the typical hacker has too few function names to
exercise her imagination on?  Who knows?

This sort of complication needs to be kept in check.  But thanks, Lars,
for actually having the consideration to ask here first.


> ---

> decode-time is a built-in function in ‘C source code’.

> (decode-time &optional TIME ZONE)

>   Probably introduced at or before Emacs version 19.29.
>   This function does not change global state, including the match data.

> Decode a time value as (SEC MINUTE HOUR DAY MONTH YEAR DOW DST UTCOFF).

> ---

> So you could do something like

> (let ((decoded (decode-time (parse-time-string ...))))
>   (setf (decoded-time-year decoded) 1975)
>   (apply #'encode-time decoded))

> or whatever.  I hate reading code that says (elt decoded 5) and then
> have to look up the doc string and then count to be able to tell what
> it's doing...

That's what comments are for.  I will hate it even more having to look
up the doc string several times, once to find out what a function does,
and once for each accessor name I've got to use; then having somehow to
memorize that long accessor name between doc string and the source code
I'm writing.  (My memory isn't good enough to note all these names on
one sweep of the doc string.)

> Does this sound like a good idea?  And if so, what should the name of
> these accessors be?  `decoded-time-' is clear, but perhaps a mouthful...

Exactly!  (decoded-time-year result) will not be better than (nth 5
result).  Both really require comments:

    (decoded-time-year result) ; An accessor function.
vs.
    (nth 5 result) ; The year.

> -- 
> (domestic pets only, the antidote for overdose, milk.)
>    bloggy blog: http://lars.ingebrigtsen.no

-- 
Alan Mackenzie (Nuremberg, Germany).