From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Daniel Hackney Newsgroups: gmane.emacs.devel Subject: Interest in "Elisp lint"-like tool? Date: Mon, 30 Jan 2012 17:45:57 -0500 Message-ID: NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 X-Trace: dough.gmane.org 1327981564 20054 80.91.229.3 (31 Jan 2012 03:46:04 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Tue, 31 Jan 2012 03:46:04 +0000 (UTC) To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Tue Jan 31 04:46:03 2012 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([140.186.70.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1Rs4fR-0002PB-Hb for ged-emacs-devel@m.gmane.org; Tue, 31 Jan 2012 04:46:01 +0100 Original-Received: from localhost ([::1]:38467 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Rs4fQ-0006nn-HS for ged-emacs-devel@m.gmane.org; Mon, 30 Jan 2012 22:46:00 -0500 Original-Received: from eggs.gnu.org ([140.186.70.92]:38288) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RrzzQ-0003dh-82 for emacs-devel@gnu.org; Mon, 30 Jan 2012 17:46:21 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1RrzzP-0005BV-0U for emacs-devel@gnu.org; Mon, 30 Jan 2012 17:46:20 -0500 Original-Received: from mail-wi0-f169.google.com ([209.85.212.169]:40490) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1RrzzO-0005B6-SM for emacs-devel@gnu.org; Mon, 30 Jan 2012 17:46:18 -0500 Original-Received: by wibhj13 with SMTP id hj13so4828958wib.0 for ; Mon, 30 Jan 2012 14:46:17 -0800 (PST) Received-SPF: pass (google.com: domain of dan@haxney.org designates 10.180.78.233 as permitted sender) client-ip=10.180.78.233; Authentication-Results: mr.google.com; spf=pass (google.com: domain of dan@haxney.org designates 10.180.78.233 as permitted sender) smtp.mail=dan@haxney.org Original-Received: from mr.google.com ([10.180.78.233]) by 10.180.78.233 with SMTP id e9mr35700910wix.0.1327963577186 (num_hops = 1); Mon, 30 Jan 2012 14:46:17 -0800 (PST) Original-Received: by 10.180.78.233 with SMTP id e9mr29810752wix.0.1327963577135; Mon, 30 Jan 2012 14:46:17 -0800 (PST) Original-Received: by 10.180.4.170 with HTTP; Mon, 30 Jan 2012 14:45:57 -0800 (PST) X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 209.85.212.169 X-Mailman-Approved-At: Mon, 30 Jan 2012 22:45:58 -0500 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 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-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:148055 Archived-At: Having done random hacking on and reading of some of the elisp libraries around the web, especially in the various ELPA archives, there is a lack of consistency across the different packages. They can range from small-ish things like newline characters to documentation styles to more significant things like the presence of autoloads, which are especially significant for packages installed via ELPA. There are a few tools which check various elements of style or consistency like `checkdoc', `package', and `byte-compile', but there's no comprehensive reference and validator for the whole range of style-like things. I've put together a preliminary list of some of the checks and warning I think might be useful. A number of these would require some sort of agreement or decision by the community (indentation style, for example), and for those, I've left the "check specification" as a question. - short docstring on first line, blank line following - document all args - specify defcustom format - custom group - keymap in mode definition - can setup purely through autoloads and custom - all customs, defuns, and modes documented, especially interactive ones - variable and face for text faces, prefer existing face or inheritance from an existing face - quote symbol references (in docstrings) - Standard indent format? What to use? - whitespace, tabs and newline policy? - Single vs. double space after end of sentence? - warn about runtime CL funcs, suggest alternatives? - document free variables? - should section character be present or not? - where do file-local variables go? - how should global minor modes be handled? - document prefix arguments for interactive commands - warn when accessing the prefix argument without it being declared in the interactive specification - standardized keybinding declaration (defvar vs. let) and specification (`kbd' vs "\C") - `global-set-key' vs. global minor mode? - Don't override reserved keys (unless you are sure) - Autoload mode custom variables - no * in docstring - header and footer comments - enable modes by custom - use `define-*-mode' rather than raw `defun' - proper copyright, license, author, version, etc. headers - warn about comments in the header not in a standard section - avoid `defadvice' - use ";;" for comments - "namespace" should match filename - warn about deprecated variables and functions - `provide' call at end of file - semver.org (or "ruby gem") version policy - order of headers? - no comment ASCII art boxes (e.g. ";;;;;; Section description ;;;;;;") - `require's at top (except when not) - in-code version number? (e.g. (defvar FOO-version "1.2.3")) - warn on `require's without declared package dependency - unnecessary `require' - complain about too many function arguments? - should keyword args be suggested? Encouraged? Discouraged? - Check for author email and home page (possibly more?) - Document public vs. private vars and functions Also, I thought there were some interesting/important behaviors which such a package would require: - Magic comment to override style checks (;;;###stop-whining) - set strictness level/style group to check - Different checks (e.g. deprecated) for different Emacs versions So you could have a group called `documentation' which would contain checks that related to comments and docstrings, for example. Then, if you wanted to run the checks without the documentation checks, you could remove the `documentation' group from the list of applied checks. As for a name, I came up with a couple (not particularly attached to any of them): - styEl (style for elisp) - elLint - elCritic (in the same vain as Perl::Critic) - CriticEl - StyleEl Some of these style choices seem fairly uncontroversial (like making sure `provide' is at the end of the file), and I think it would be a boon to the community to have some further standardization around best practices and expected patterns. This becomes especially relevant in light of the "packagization" of an increasing number of Elisp libraries, as they do not go through the rigors of making it into Emacs core. What do you all think? -- Daniel M. Hackney