From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Alan Mackenzie Newsgroups: gmane.emacs.devel Subject: Re: Decoded time accessors Date: Sun, 7 Jul 2019 21:43:26 +0000 Message-ID: <20190707214326.GD4053@ACM> References: Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="120386"; mail-complaints-to="usenet@blaine.gmane.org" User-Agent: Mutt/1.10.1 (2018-07-13) Cc: emacs-devel@gnu.org To: Lars Ingebrigtsen Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Jul 07 23:43:39 2019 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1hkEwb-000V8r-CF for ged-emacs-devel@m.gmane.org; Sun, 07 Jul 2019 23:43:37 +0200 Original-Received: from localhost ([::1]:37130 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.86_2) (envelope-from ) id 1hkEwa-0003Zu-AF for ged-emacs-devel@m.gmane.org; Sun, 07 Jul 2019 17:43:36 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:46096) by lists.gnu.org with esmtp (Exim 4.86_2) (envelope-from ) id 1hkEwU-0003Zj-QY for emacs-devel@gnu.org; Sun, 07 Jul 2019 17:43:32 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hkEwT-00063r-89 for emacs-devel@gnu.org; Sun, 07 Jul 2019 17:43:30 -0400 Original-Received: from colin.muc.de ([193.149.48.1]:60810 helo=mail.muc.de) by eggs.gnu.org with smtp (Exim 4.71) (envelope-from ) id 1hkEwT-00062V-0K for emacs-devel@gnu.org; Sun, 07 Jul 2019 17:43:29 -0400 Original-Received: (qmail 59527 invoked by uid 3782); 7 Jul 2019 21:43:26 -0000 Original-Received: from acm.muc.de (p2E5D59C3.dip0.t-ipconnect.de [46.93.89.195]) by colin.muc.de (tmda-ofmipd) with ESMTP; Sun, 07 Jul 2019 23:43:26 +0200 Original-Received: (qmail 26389 invoked by uid 1000); 7 Jul 2019 21:43:26 -0000 Content-Disposition: inline In-Reply-To: X-Delivery-Agent: TMDA/1.1.12 (Macallan) X-Primary-Address: acm@muc.de X-detected-operating-system: by eggs.gnu.org: FreeBSD 9.x [fuzzy] X-Received-From: 193.149.48.1 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:238397 Archived-At: 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).