From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on inbox.vuxu.org X-Spam-Level: X-Spam-Status: No, score=-3.4 required=5.0 tests=DKIM_SIGNED,DKIM_VALID, DKIM_VALID_AU,MAILING_LIST_MULTI,RCVD_IN_DNSWL_MED,UNPARSEABLE_RELAY autolearn=ham autolearn_force=no version=3.4.4 Received: (qmail 2939 invoked from network); 1 Dec 2020 16:48:28 -0000 Received: from zero.zsh.org (2a02:898:31:0:48:4558:7a:7368) by inbox.vuxu.org with ESMTPUTF8; 1 Dec 2020 16:48:28 -0000 ARC-Seal: i=1; cv=none; a=rsa-sha256; d=zsh.org; s=rsa-20200801; t=1606841308; b=Uy6bh3iM6j0XdBx+PbFbNQIXexYCdPG2clo3Yu8gsOxmgCC7xoBFEtEnFHBJV4hSRlEGp6cKup FF38TuCY3RUAwSBpvIXuPGbXkcpYP9upwRp8LO+xH9nnBYTU4d62L058B2FNTjlHPa/AuR1/K9 0u0HeeeIymmJgZOM6vBgGg4dIw6AWiJnlC1k2w25aYO/cnsa/6EQYfNRTeCxXnVoKYIBNLKbW3 DVEWNkIECAVVkQtd3JvV/44g2IKNkY8it60j1NfFQR/3LQGBINQZD9wbeb5pdBSHrDL36GVo56 eJGRP8LjgEr3fIhp+NzLPdz3Y9rFOuJkJvVRYRzUTZvKpA==; ARC-Authentication-Results: i=1; zsh.org; iprev=pass (out4-smtp.messagingengine.com) smtp.remote-ip=66.111.4.28; dkim=pass header.d=daniel.shahaf.name header.s=fm2 header.a=rsa-sha256; dkim=pass header.d=messagingengine.com header.s=fm1 header.a=rsa-sha256; dmarc=none header.from=daniel.shahaf.name; arc=none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed; d=zsh.org; s=rsa-20200801; t=1606841308; bh=DAAuyMUyRXmzpwJ6MZXxOa87ZhOR06vVRvdIBw8SpQw=; h=List-Archive:List-Owner:List-Post:List-Unsubscribe:List-Subscribe:List-Help: List-Id:Sender:In-Reply-To:Content-Type:MIME-Version:References:Message-ID: Subject:To:From:Date:DKIM-Signature:DKIM-Signature:DKIM-Signature; b=YZFPZF7Xr2BrrJuRPWk+ryTVMHdVkFhXRD5hIFNyUrn3ZXJY0qay9aLpEaEj6le7FueWPBYDk0 c3HoHMZZ2SA38Q6vC8ombDRf1SLfa66qlPZDUHGcxa4IwJjdi4+I1TPHaRogenZOW5yJBYM8XD w7bdfPsRz1bFIl3TlgViuyoPmf2jvmUPFGV55q6s6KD0AInEhsi6tktxsYM2rEuFNrYX7WPpYE vTuBjyU8897hEHIhdsnGZR7mcHGm6BWorlew2s1sSaPIZaqQOxYaL1IS3HsrgVYFFBk1QWwrFO eley4KNCdOzUqeRhjJAbLqQ0l+WDnYGv7+wcHbT3ktwABA==; DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=zsh.org; s=rsa-20200801; h=List-Archive:List-Owner:List-Post:List-Unsubscribe: List-Subscribe:List-Help:List-Id:Sender:In-Reply-To:Content-Type:MIME-Version :References:Message-ID:Subject:To:From:Date:Reply-To:Cc: Content-Transfer-Encoding:Content-ID:Content-Description:Resent-Date: Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID; bh=N5BTvECfFgjZ0ozQdSxlxhXlvydNyZcKCmtQNNle5II=; b=zb/lyAwiZFlWZkcGqWjn62ZJa9 OtV3BJJRiOeCl59a4IP6GEa6oImL9CSMYAI70vPvAHPlvShfzbJQioJL8U9hdGDjKv9RBG4PedGY9 nxP41Wev9bovT83CeajZNVdzlh9esIMVdzzN5i1r7cLco8mfD+hI4FqSEcuTDP3m118+FxFeYA8c/ JvN/YadIiHOPsnn/FPrg+KEM/RKSdpvu8zEcATHxjBIz9adpB4AO8iFBDKXTQ7ZOBnGcJmqn7quW6 3mz05cyEWlu861p/ZXLEBxUeeWRWqhf2S5nZTMqDmAHW/ZONzSYgPI867qi/eyzsdB3wp9zrURgvW TLvtIyfQ==; Received: from authenticated user by zero.zsh.org with local id 1kk8pG-000Fpc-6O; Tue, 01 Dec 2020 16:48:26 +0000 Authentication-Results: zsh.org; iprev=pass (out4-smtp.messagingengine.com) smtp.remote-ip=66.111.4.28; dkim=pass header.d=daniel.shahaf.name header.s=fm2 header.a=rsa-sha256; dkim=pass header.d=messagingengine.com header.s=fm1 header.a=rsa-sha256; dmarc=none header.from=daniel.shahaf.name; arc=none Received: from out4-smtp.messagingengine.com ([66.111.4.28]:46951) by zero.zsh.org with esmtps (TLS1.2:ECDHE-RSA-AES256-GCM-SHA384:256) id 1kk8ot-000Ffh-PH; Tue, 01 Dec 2020 16:48:04 +0000 Received: from compute2.internal (compute2.nyi.internal [10.202.2.42]) by mailout.nyi.internal (Postfix) with ESMTP id 4E1E15C00F0; Tue, 1 Dec 2020 11:47:45 -0500 (EST) Received: from mailfrontend2 ([10.202.2.163]) by compute2.internal (MEProxy); Tue, 01 Dec 2020 11:47:45 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= daniel.shahaf.name; h=date:from:to:subject:message-id:references :mime-version:content-type:in-reply-to; s=fm2; bh=N5BTvECfFgjZ0o zQdSxlxhXlvydNyZcKCmtQNNle5II=; b=oT32+1CHHd6hR3C7sPF9O57W1Ph0Ns aivPaG7loWdGwIY9azpbQNcoBx1PYYImYSDloyDOhwzyLl1AQ1NYPHC7IWEcRVXE zeU69x1UytffUlKEVH6zHdq0b8bfmI/M8pDnHzvRcafPlDmsNECEVMQ8DVoybEX0 BDZPWXGhggLPimAMSb4evYtnK5Gtvi1WtS2waVrjRQN7tm0VbdxOxTYHk7yVDa/H xzTnGk+fzbbjYMrzw5Q5qtA8ydOiexuAWzGOxtyGS3msd/E2LuVoVQrdySfPabq4 tQ/ndnv4obMaXoGq1VFXQSTl1V5RuVbW40ZrurkSSWTmtIDCxUyTGI7Q== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=content-type:date:from:in-reply-to :message-id:mime-version:references:subject:to:x-me-proxy :x-me-proxy:x-me-sender:x-me-sender:x-sasl-enc; s=fm1; bh=N5BTvE CfFgjZ0ozQdSxlxhXlvydNyZcKCmtQNNle5II=; b=EDwGWLj8jIkiva6yyNqqOX Zy6RAPUg/Vp3ZuVGqVzVsfKylyDTX7AEjZPjapFc9TbF4XfUUnVSQV/Fal4o9PmE 7iiSmMuluVRNSwIRBeIqY1Xp7jK2BtDDo0mPPCDG5wAZLuKclpjNobp6yQevIwha 8BuUhwtkZm0oJibP2YSz1wwuZw1IevbfaB6zMgNkk8+wRo5aqQakehbr8rcN3jky gerwUlcQ3WT37yf6TTk5N7YsfAQC8ccQ9xwTryLaszdPRtFFb35iJyDt0itW3zBu 8gv4OLC/GiwZwphEVzHXJ5L0mhlUDlQwsmCayDsbl/HQB6CoNFWRWRV8mRg33uqw == X-ME-Sender: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgedujedrudeivddgleehucetufdoteggodetrfdotf fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfqfgfvpdfurfetoffkrfgpnffqhgen uceurghilhhouhhtmecufedttdenucenucfjughrpeffhffvuffkfhggtggujggfsehttd dttddtredvnecuhfhrohhmpeffrghnihgvlhcuufhhrghhrghfuceougdrshesuggrnhhi vghlrdhshhgrhhgrfhdrnhgrmhgvqeenucggtffrrghtthgvrhhnpeeuveekfeffueefhe efhfegffefvdeitdehtdegleejledviefhveejfeetgedvkeenucfkphepjeelrddukedt rdeikedrudefheenucevlhhushhtvghrufhiiigvpedtnecurfgrrhgrmhepmhgrihhlfh hrohhmpegurdhssegurghnihgvlhdrshhhrghhrghfrdhnrghmvg X-ME-Proxy: Received: from tarpaulin.shahaf.local2 (bzq-79-180-68-135.red.bezeqint.net [79.180.68.135]) by mail.messagingengine.com (Postfix) with ESMTPA id 6F9461080057 for ; Tue, 1 Dec 2020 11:47:44 -0500 (EST) Received: by tarpaulin.shahaf.local2 (Postfix, from userid 1005) id 4Clp1V2stmz4W0; Tue, 1 Dec 2020 16:47:42 +0000 (UTC) Date: Tue, 1 Dec 2020 16:47:42 +0000 From: Daniel Shahaf To: zsh-workers@zsh.org Subject: Re: zsh coding style (was about a limit patch review) Message-ID: <20201201164742.GA24476@tarpaulin.shahaf.local2> References: <20201123214942.hi2rx7n3jk25ucmd@chazelas.org> <74327-1606347813.918593@HxCz.NV4p.AwzH> <20201126205819.dbncs24ppnw3pdny@chazelas.org> <20201127163949.GD26720@tarpaulin.shahaf.local2> <20201127201342.t4uthqbfwuhzgevz@chazelas.org> <808eb7ef-fe44-474a-ba85-6144b95b16c2@www.fastmail.com> <20201128065201.54ngcgcyklyfggm6@chazelas.org> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20201128065201.54ngcgcyklyfggm6@chazelas.org> User-Agent: Mutt/1.10.1 (2018-07-13) X-Seq: 47709 Archived-At: X-Loop: zsh-workers@zsh.org Errors-To: zsh-workers-owner@zsh.org Precedence: list Precedence: bulk Sender: zsh-workers-request@zsh.org X-no-archive: yes List-Id: List-Help: List-Subscribe: List-Unsubscribe: List-Post: List-Owner: List-Archive: Archived-At: Stephane Chazelas wrote on Sat, Nov 28, 2020 at 06:52:01 +0000: > Believe it or not, I had "(boolean)" and a "Returns:..." > initially, and took them out before submitting as they would > have been out of character among the other functions in that > file (and the rest of the code from a cursory look) which are > rather minimalist and avoid stating the obvious. Every docstring should state the permitted values of each parameter and the possible return values. Yes, some existing functions fall short of this standard, but there's no reason not to hold _new_ functions to it. That doesn't pay off existing technical debt, but it avoids accruing further debt. > This function description is already by far the least dry and > probably the most RY in that file. To the point that I'm > wondering if you're pulling my leg for being overly wordy here. No, I'm not. > About the _p suffix, the only usage of it in the code (beside > has_p) I could find for it was > save_params(Estate state, Wordcode pc, LinkList *restore_p, LinkList *remove_p) > in exec.c, but that "p" looks like it's for "pointer" (as in > return value, though could also be "param"), not "predicate". > I've never heard of _p for predicate before, but then again I've > not done much C development lately. > I hear it's more common in lisp circles. It's a form of Hungarian notation. > I'm all for having a coding style. Even a template for function > header could be useful. That would probably help make the > code more legible (though in general, I do find zsh's code > pretty legible, orders of magnitude more so than ksh93's for > instance) > > I did read Etc/zsh-development-guide before submitting my first > patch. The relevant bit there is: > > } * Function declarations must look like this: > } > } /**/ > } int > } foo(char *s, char **p) > } { > } function body > } } > } > } There must be an empty line, a line with "/**/", a line with the > } type of the function, and finally the name of the function with typed > } arguments. These lines must not be indented. The script generating > } function prototypes and the ansi2knr program depend on this format. > > Maybe that document could be updated to say more precisely how > new code should look like if we're to enforce a new coding > style. I wasn't trying to enforce a new coding style. I was simply reviewing the docstring to the same standard I've reviewed every other docstring I've ever reviewed, either on this list or elsewhere. Cheers, Daniel