From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: akater Newsgroups: gmane.emacs.devel Subject: Codifying some aspects of Elisp code style and improving pretty printer Date: Wed, 29 Sep 2021 18:01:47 +0000 Message-ID: <87o88bntv8.fsf@gmail.com> Mime-Version: 1.0 Content-Type: multipart/signed; boundary="=-=-="; micalg=pgp-sha512; protocol="application/pgp-signature" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="39258"; mail-complaints-to="usenet@ciao.gmane.io" To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Wed Sep 29 20:14:04 2021 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1mVe5i-0009xs-P9 for ged-emacs-devel@m.gmane-mx.org; Wed, 29 Sep 2021 20:14:02 +0200 Original-Received: from localhost ([::1]:37148 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mVe5h-0000s0-Ru for ged-emacs-devel@m.gmane-mx.org; Wed, 29 Sep 2021 14:14:01 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:57032) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mVe51-000089-ET for emacs-devel@gnu.org; Wed, 29 Sep 2021 14:13:19 -0400 Original-Received: from mail-ed1-x531.google.com ([2a00:1450:4864:20::531]:40568) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1mVe4z-0007Vn-Nq for emacs-devel@gnu.org; Wed, 29 Sep 2021 14:13:19 -0400 Original-Received: by mail-ed1-x531.google.com with SMTP id g8so12204192edt.7 for ; Wed, 29 Sep 2021 11:13:16 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:subject:date:message-id:mime-version; bh=uNBi4BLA2VlpR4TEutaOxveVODFZlTT//6dhneALyYs=; b=f9LUyrNuMY2meyK78IbmzGTHTjKn+EQWYli1I+VCplR9YuCodu4qRVfeIyb+PI55zY DRMIMhgTmKuF1adOgakpYwYCz+8NR+Ecm1200ATp/sxOAs5YI2JyBWGHMfU4J0Lhj3YC p881r+f3FxdUWKGSwKLwrdg0qnBytNJiLkcIyWApsltle3Ab67SDqRsxlDSC7BXrccIi sJLKakWXnP8MA+6Albf6mkC/FJwSioX8bI8WBALAFZLo9pNyXd7xlHmSNu5XwfNlX05b /W4SrfAGVo34ebAAVvwsQad1n2eH0yxBF+Rtpry6B9DwDdGP8RYbeojYQ5xlpLclyL2O AN3A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:subject:date:message-id:mime-version; bh=uNBi4BLA2VlpR4TEutaOxveVODFZlTT//6dhneALyYs=; b=68l4SJXBiaEt3yG6IfeRMpDfcaKmRYJaDER/FflsKDaxozR2AwWuVG3pFzlOVSNEt1 UnVsckLmJ2CInJ9Of5761XA0ZOMmreFWuKm9Mf/ijipZ2+wID3XyCQ4Vyz8SorrERlXx DMaOn/ppPPoYIgdjv9pPb1qU+2X9AJ194KBZoU7iBPwX+QjJBTK9JXN2g/+vmZr7w7qc VNic6fF2K8oaFWwt+C20yUcJVdBnWqPqcLXGR3UxqEH1ASRlLw1zbj9fKM2+YjGlf/73 EN3kH56ISoP1LJHPyTJRkL26oMHet18ok+BnLYyfPQ21oFNmSvST/3QfemGdnacS2cnX E5NQ== X-Gm-Message-State: AOAM531dVo1KJwlW3e6O4ZyjP0B6oJc3bhc08OfO3LcdT9A+Z2CWLoUL BwO6fFbOlpG9kVTLOkP+MxCy7OhVZMg= X-Google-Smtp-Source: ABdhPJyyaEcNSnNQXk9F6wuJIvj+vqI/l4fcUkLn9OGLkWESqpTKxwlRMmOaQQVXkfqfkje8I9e7eg== X-Received: by 2002:a50:8d85:: with SMTP id r5mr1573595edh.312.1632939195684; Wed, 29 Sep 2021 11:13:15 -0700 (PDT) Original-Received: from localhost ([185.31.175.220]) by smtp.googlemail.com with ESMTPSA id j14sm382871edl.21.2021.09.29.11.13.14 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 29 Sep 2021 11:13:15 -0700 (PDT) Received-SPF: pass client-ip=2a00:1450:4864:20::531; envelope-from=nuclearspace@gmail.com; helo=mail-ed1-x531.google.com X-Spam_score_int: -7 X-Spam_score: -0.8 X-Spam_bar: / X-Spam_report: (-0.8 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001, RCVD_IN_BL_SPAMCOP_NET=1.347, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=no autolearn_force=no X-Spam_action: no action 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-mx.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.io gmane.emacs.devel:275821 Archived-At: --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Rgrepping lisp/emacs-lisp alone for =E2=80=9C(let=E2=80=9D and =E2=80=9C(if= =E2=80=9D demonstrates that there is a reasonable practice at least =2D of keeping =E2=80=9Cthen=E2=80=9D on the same line as =E2=80=9Cif=E2=80= =9D sometimes =2D of having several let bindings in =E2=80=9Clet=E2=80=9D on the same lin= e, especially if they are all symbols except maybe some first ones. There is an informal consensus that it's worth it to use whitespace wisely to keep Lisp forms concise vertically as well as horizontally. I think if the idea is recognised as useful it better be explicitly stated as such rather than remain folklore. I don't see this practice codified neither in elisp nor eintr Info nodes nor anywhere in Lisp literature for that matter. I asked in commonlisp channel on libera.chat and nobody seems to know of any text like that; pointers are welcome if I missed something. True, this is largerly a matter of personal style. However, there is also some accumulated experience which I think is worth aggregating. And no style is actually 100% personal when we collaborate. I paid some attention to the issue for some time while writing (E)Lisp code. There are still some practices I'm not sure about. E.g. apparently there's no practice to start the first subform of unwind-protect on the same line as unwind-protect when line width allows it; I find this surprising as I think this significantly decreases readablity of unwind-protect forms. What follows is a draft of relevant style guidelines as I see it. At the very least, it can serve as a basis for improving the currently used pretty printer that prints Elisp forms (which still inexplicably insists that let forms' bindings should start on a new line, for example). Automatic indentation should not attempt to be smart about line splits but pretty printer should. I'd welcome relevant bits of github.com/bbatsov/emacs-lisp-style-guide as well but the guide mentions issues Emacs seems to deal on its own automatically so I'm not sure. Also, there may be copyright issues. When it comes to accessing such information from within Emacs, I could only find something in (recent) compiler warnings, about long docstrings, and some other notes about docstrings in CONTRIBUTE file. Since it has sporadic notes on docstring style, CONTRIBUTE likely should also reference the style guide as well as Emacs Lisp Coding Conventions Info node. So here's the draft. Emacs Lisp source code layout guidelines =2D Rule of thumb: General form should look like (f x y z) However, if sequences f x1 ... xn, y1 ... ym, ..., z1 ... zk are short as a whole, it is preferred to (f x1 ... xn y1 ... ym ... z1 ... zk) especially if expressions on the same line are close conceptually, e.g. (a) key-value pairs, including those with keyword arguments, or (b) pairs of arguments in setq, setf and similar forms. =2D =E2=80=9CShort as a whole=E2=80=9D necessarily means =E2=80=9Cfits into= a single line of recommended line width, together with all opening parens=E2=80=9D but this condition is not sufficient. =2D In let, let* and similar forms, a single line can hold as many bindings represented by symbols rather than lists, as long as they are short as a whole. =2D In let* and similar forms, a binding with initial value that depends solely on a previous (but not necessarily immediately previous) value, can be kept on the same line as its dependency as long as they are short as a whole. =2D In let, let* and similar forms, if it is posible to arrange variables so that conceptually close ones share the same line, it is preferred to do so. =2D In most (indent n) forms, it is preferred to start (n-1)th subexpression on the same line as the head symbol if the subexpressions in question are short as a whole and if it allows to keep the overall form concise both horizontally and vertically; note that it applies to forms ignore-errors and unwind-protect. =2D The former applies to cl-loop, cond, let, if forms which do not have (indent ..) in their specs but which can nevertheless be considered for our purposes as (indent 0), (indent 0), (indent 1), (indent 2) forms correspondingly. =2D Aside from the very first one, cl-loop keywords should start the lines. =2D Two or more forms, short as a whole, that perform what's essentially a single step of a loop can be kept on the same line. =2D =E2=80=9CShort=E2=80=9D, =E2=80=9Cmost forms=E2=80=9D, =E2=80=9Csimilar= forms=E2=80=9D in the above paragraphs are subjective so the final decision on whether keeping sexps on the same line hampers readability or not is up to a maintainer of the Elisp codebase in question. Arguing about such things with maintainers is likely a waste of time. Thus, the maintainer's decision on line splits should be considered final. Refactoring / cleanup edits that deal with line splits better be left to maintainers, or outsourced by them to someone whose personal style they explicitly trust enough to avoid any arguments about this matter. --=-=-= Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQJLBAEBCgA1FiEEgu5SJRdnQOF34djNsr6xYbHsf0QFAmFUqgsXHG51Y2xlYXJz cGFjZUBnbWFpbC5jb20ACgkQsr6xYbHsf0Rv/BAAuORfMgZTiypdi/bGty/gZTn+ yRPaWa32YgTNBYLZUX0A9a+q8QNQxx135mZ7ExFXjmfxCxO1N0eOFVDsyzWPrV/R Lhk8E8Z7z63yrtyMAM1vj9pSPk8pWcZwD1i3+cmhofJClWaFFnxWk0X8B/GZ/trb PPj5cJc/FRcyx8MEl5P9r6W7Y2yk+8ngmN3DylXLOGKflVBjMVE4KgRAfArLlIy6 bwVuRCymoGxIIYfhRlpSInV3FoimWAMvDMSYA3i2Pa+CiHD3q3MdnguoWXfkqj3e pSwuOMGjlOOXPCpjBYhzpklOt34EESKA5ztSQDtJ3s8PkQ1HmUuydMq9lImS2vai tA6qLonM+Kl4qQp8Ncjfs+81nuVMLhi7yPRkWqLeKhCoamX9E0odoBn/WXEwIt0d jkrGUP0N+k8rn/uBQPo5UQWp9jABwecFDhVaYtox1tCMM492OqMRmTMPm1VNsRNk LZPSz/XKbrEIBFuBR6f94aHyEpQoyGCjoEgs7wcVuu8JZAeRL18V8iV2LGnPIcUi /bFruMADl+Ie1l3rUPJvdBBrgs8Fzl1OZWVFbAgkd0uXhIyIzO8i5NPDXqSkyCNN jnxIiAXRpqWClxMmWelVfA7NPYrH2zCnIKxJ7FutsTzWhHmttT6Ao+nmH2s39gEt Gb4SaGI8gxz+TswBTbk= =IJS+ -----END PGP SIGNATURE----- --=-=-=--