From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.devel Subject: RE: Predicate for true lists Date: Sun, 8 Jul 2018 08:15:26 -0700 (PDT) Message-ID: <3a8f5e42-99fd-4814-bbaf-de6f11866492@default> References: <87fu3vdjjk.fsf@tcd.ie> <87bmcqhhsf.fsf@tcd.ie> <87in6xgtpb.fsf@tcd.ie> <2af892df-26cb-60b2-4fd8-067fcb3d32e9@cs.ucla.edu> <87r2kh9uwx.fsf@tcd.ie> <83h8lcnbxb.fsf@gnu.org> <6fc589d1-2c21-3e9b-be47-b7700f61642d@cs.ucla.edu> <831scflefs.fsf@gnu.org> <5d0d79d3-6291-fbf0-1028-064f86787483@cs.ucla.edu> <837em7jrag.fsf@gnu.org> <87k1q7ytmr.fsf@tcd.ie> <83o9fjhvnk.fsf@gnu.org> <87efgfyomt.fsf@tcd.ie> <83k1q7ht51.fsf@gnu.org> <17d4bfb6-4c14-901f-716f-4aa50386eb9d@cs.ucla.edu> <6a48d13f-9d6b-f9a6-3b41-6ea0c8294d81@cs.ucla.edu> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: blaine.gmane.org 1531062869 13627 195.159.176.226 (8 Jul 2018 15:14:29 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sun, 8 Jul 2018 15:14:29 +0000 (UTC) Cc: emacs-devel@gnu.org To: Paul Eggert , Eli Zaretskii , "Basil L. Contovounesios" Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Jul 08 17:14:25 2018 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fcBOK-0003MV-JA for ged-emacs-devel@m.gmane.org; Sun, 08 Jul 2018 17:14:24 +0200 Original-Received: from localhost ([::1]:37301 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fcBQM-0003Rk-MS for ged-emacs-devel@m.gmane.org; Sun, 08 Jul 2018 11:16:30 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:53563) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fcBPb-0003RJ-NV for emacs-devel@gnu.org; Sun, 08 Jul 2018 11:15:45 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fcBPa-0005rd-GZ for emacs-devel@gnu.org; Sun, 08 Jul 2018 11:15:43 -0400 Original-Received: from userp2130.oracle.com ([156.151.31.86]:52922) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1fcBPW-0005pP-BM; Sun, 08 Jul 2018 11:15:38 -0400 Original-Received: from pps.filterd (userp2130.oracle.com [127.0.0.1]) by userp2130.oracle.com (8.16.0.22/8.16.0.22) with SMTP id w68FEW1m184791; Sun, 8 Jul 2018 15:15:29 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=mime-version : message-id : date : from : sender : to : cc : subject : references : in-reply-to : content-type : content-transfer-encoding; s=corp-2018-07-02; bh=LjksM40STvJX3BulSK+4oPKCkeWGZ4Gh1arl1Ftp6m4=; b=0Tk2GmHAaBFHnDEp65YOgWR8JgpQa9uyUucnUby+YXeZzRpT0fkRAvYgx8suLh53blo+ AtFdfmEQn9JHIaClHyBiXNkaO70qBlWfnWmUFJLcelDD4SmyzZ6RBDvjeVFEeg4fP7Kh JnGmmjtSNqgw2A2AXdsDmOn6x3Zv5ub61QZVw9kirjR+2oOYrd5CanTdnOduBgQ+oHDk Zo/OrSqhdDZddxsGsyNCbuzulcIQV4edzlWfnUKGcI1OknWjRDmS/qoOPUCtzSOW03Rw 6mtqxANQKF9hL02sDDm3vJYxSk/N4E5nv/CnAHMr/YeRDSlr3BQRXSpoiDPQrDrQKyBS tw== Original-Received: from aserv0022.oracle.com (aserv0022.oracle.com [141.146.126.234]) by userp2130.oracle.com with ESMTP id 2k2p75ssja-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Sun, 08 Jul 2018 15:15:29 +0000 Original-Received: from aserv0121.oracle.com (aserv0121.oracle.com [141.146.126.235]) by aserv0022.oracle.com (8.14.4/8.14.4) with ESMTP id w68FFSqA029424 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Sun, 8 Jul 2018 15:15:28 GMT Original-Received: from abhmp0015.oracle.com (abhmp0015.oracle.com [141.146.116.21]) by aserv0121.oracle.com (8.14.4/8.13.8) with ESMTP id w68FFRW0008201; Sun, 8 Jul 2018 15:15:27 GMT In-Reply-To: <6a48d13f-9d6b-f9a6-3b41-6ea0c8294d81@cs.ucla.edu> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.4705.0 (x86)] X-Proofpoint-Virus-Version: vendor=nai engine=5900 definitions=8947 signatures=668705 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=2 malwarescore=0 phishscore=0 bulkscore=0 spamscore=0 mlxscore=0 mlxlogscore=825 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1806210000 definitions=main-1807080184 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x [generic] [fuzzy] X-Received-From: 156.151.31.86 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 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:227108 Archived-At: > > We should document the intended behavior, including > > the error behavior. >=20 > Documenting every function's behavior completely, in that function's doc = string or manual section, would waste not only our time, but also time spen= t by users reading the documentation. Nobody does that, for any nontrivial = GNU program I'm aware of. Common sense should prevail, and "document every = bit of behavior" absolutism would cause more trouble than it'd cure. Thank = goodness we don't do that, and have never done that. Strawman. I never said that every function's behavior needs to be documented completely. Nor is the text you quoted, "document every bit of behavior" something I said - it's just an invention on your part. That strawman distracts from your argument that not documenting behavior can protect future changes from being backward incompatible. And it distracts from my argument against that (misguided) argument. First, I specifically distinguished between design (intended behavior) and implementation (actual behavior, with bugs). It's not at all about documenting "every bit of behavior". And yes, this, like all documentation decisions, is always a judgment call, and yes, such judgment calls for common sense. The question here is whether (1) documenting error-handling behavior in this case is useful to users and (2) whether not documenting it somehow insulates future changes from being backward-incompatible. My point was that not mentioning error-handling behavior does _not_ make a future change less backward-incompatible. We should own the current design and, yes, document it for users. And as Eli mentioned, if and when the design changes we can update the documentation accordingly. That's part (2) of the overall question - the only part I actually addressed, as a reply to your ("absolutist"?) statement to the contrary. And that part (2) applies generally: No documentation omission or spin can protect against backward compatibility. It's a mistake to think or pretend that you're not breaking backward compatibility just because the behavior you change was never documented. Compatibility is about behavior, not just its description. As for part (1), which I did not speak to, there is no hard-and-fast rule. Speaking to it now: I think it probably is useful in this case (for `*'). But that's just one opinion, and given good counter-arguments I might change it. I don't feel strongly about it - I don't much care about this particular case. I posted my reply only because of the wide-ranging, misleading argument you made about doc silence protecting future changes - IOW, part (2). Generally speaking, just because makers of non-free software sometimes try to hide aspects of a design from users, that's no reason why free software should do the same. We have nothing to hide. That does not provide an imperative to pedantically "document every bit of behavior" - no connection. What it does is remove any special incentive (commercial, "intellectual property" related, etc.) to self-censor or otherwise not give users info that could help them. That we don't have a need to hide info does not imply that we need to bore or confuse users with a wall of unhelpful details. Whether this or that bit of info actually helps users, and how much, is a judgment call, on a case-by-case basis. There is no imperative to pedantically document everything (about design or implementation) that derives from the argument I made, nor does my own opinion in this or that case produce such an imperative. --- It's probably worth being clear about another aspect of this. It's quite possible to, by _design_, intend that some part of the currently implemented behavior is "undefined". In that case, yes, there is no explicit commitment to users about that particular bit of behavior. My own opinion is that it can often be a good idea in such a case to explicitly call out that that bit is undefined. That serves as an explicit warning, of sorts, that the behavior might well change in the future. (Any behavior might change in the future; this points out that this particular behavior is undefined.) In the case at hand, is the error-handling behavior of arguments part of the design or just something to be considered undefined - implemented but not really intended? I think, from the discussion, that it's part of the design, but perhaps not? But even in the case where something is considered undefined, and even with an explicit warning about it, a backward-incompatible change is just that - it doesn't become less backward-incompatible just because we excluded that part of the behavior from the design. Backward incompatibility is about actual behavior, always. "The design didn't really change" is not a welcome answer to "You broke my code". It's pretty much a cop-out. This is not a legalistic point of view. It's a view centered on users. It's not about whether the software producer can be held liable or is better able to resist a lawsuit. It's about what is most useful for Emacs and its users.