From patchwork Tue Jul 30 07:24:33 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Patrick Steinhardt X-Patchwork-Id: 13746828 Received: from fout5-smtp.messagingengine.com (fout5-smtp.messagingengine.com [103.168.172.148]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 8A394190496 for ; Tue, 30 Jul 2024 07:24:38 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=103.168.172.148 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1722324280; cv=none; b=nKhj1IhkUTWHAAdI6Nn2kPQtW1AzLclxr+ek3NRgQidDntYbkovz6+6K6DqjqSuEkTbJBv7tLAHqaeeuVG+DVH2+fIx7jjQy66c6pdIOw0BftT1Sdik/ByO++evYOM/TpBDWE1g0Pc8tNysnnE1fOcYiPbowz3+4GpWcyl3iEbw= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1722324280; c=relaxed/simple; bh=GgLpQoRv7Fx21M1XDEgGZzZUV/9xyDuQmC82RwPD8ws=; h=Date:From:To:Cc:Subject:Message-ID:References:MIME-Version: Content-Type:Content-Disposition:In-Reply-To; b=iG4blkOEDBTJDMtSL7VlHQlgXJQi0M78SciijZEkLymXkTzADLFI5hkJ9stO6dm6EVzWbII+BRyn+dXCF4NBRMLh55nel2UVwaWWzwbZiv7ec5o4aTTLTd9HUQlXbiNDr2aWsNVCeNyh09iVQoiIQXXHzbGlp+VbBu8z1mNFCPA= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=pks.im; spf=pass smtp.mailfrom=pks.im; dkim=pass (2048-bit key) header.d=pks.im header.i=@pks.im header.b=L9/whRTR; dkim=pass (2048-bit key) header.d=messagingengine.com header.i=@messagingengine.com header.b=Plzq7px9; arc=none smtp.client-ip=103.168.172.148 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=pks.im Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=pks.im Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=pks.im header.i=@pks.im header.b="L9/whRTR"; dkim=pass (2048-bit key) header.d=messagingengine.com header.i=@messagingengine.com header.b="Plzq7px9" Received: from compute5.internal (compute5.nyi.internal [10.202.2.45]) by mailfout.nyi.internal (Postfix) with ESMTP id 75DD513807B8; Tue, 30 Jul 2024 03:24:37 -0400 (EDT) Received: from mailfrontend1 ([10.202.2.162]) by compute5.internal (MEProxy); Tue, 30 Jul 2024 03:24:37 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=pks.im; h=cc:cc :content-type:content-type:date:date:from:from:in-reply-to :in-reply-to:message-id:mime-version:references:reply-to:subject :subject:to:to; s=fm3; t=1722324277; x=1722410677; bh=YhklpRPYhG tG/gtSI4jjNDmA5UEWNtTwK3lJxQGV318=; b=L9/whRTR1jk0p43bmUFhePdRJ5 q8nGYCcPqjoxLqXUflFS6+1WzxpOb5rghiW2GPXj8XumjuaXWtx7u6ZMRyGhSCpe 9hKE/cPHjmeKsQjF6/burde1nMoxzNPrOIaf2g3nzN0R88/iscG6YHag2fyQQ2AC HQIRm764TRIJWJHuuzelFcGQQJwF62xXsmORA25D+xuazD1tQRPLGJcyYzXWGLcv sM5yRherRdvlX4i2WAEOadAk+CZEoM/cNj6qO4v/VPNf2xOX+nRDH/RbAw/fH6F8 yRv1PTH3xLQ3DBqiO0uxUOAYNSUgS1raGeYOjhk3orA9x1r0Ha7ANw0GZykQ== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:cc:content-type:content-type:date:date :feedback-id:feedback-id:from:from:in-reply-to:in-reply-to :message-id:mime-version:references:reply-to:subject:subject:to :to:x-me-proxy:x-me-proxy:x-me-sender:x-me-sender:x-sasl-enc; s= fm3; t=1722324277; x=1722410677; bh=YhklpRPYhGtG/gtSI4jjNDmA5UEW NtTwK3lJxQGV318=; b=Plzq7px93S1qbH/1qvcy3ooBHQZ98P2vsKH9c6rtAaJv ZUepqVVzUCibIq2viXedxN+EsTntg0d5qoAjD5EFpqaZjPI2jZM3kN1cbj9BWY9y vimu5YbieuTH5blb4/PT5gvCrfyGrwNAoNuuo/jL9AXdNLcDyjOAgJ6eRSPYEtjD i1zABI4PmdJsoK3BPhU0eSxTV/uVKYzKruP6L1qp7mn1bprXHzn76AtfsY2st0rD gnsy0/hkUP19RJhCmsFixKnb1x4+JaRa2K63Ohf6ueS1SmorCfIrIh11VQmnRvSi sHKJlTufrQLe/UXcFX315IWGcs0mLb1ILj6xs8VUHQ== X-ME-Sender: X-ME-Received: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeeftddrjeefgdduvdefucetufdoteggodetrfdotf fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfqfgfvpdfurfetoffkrfgpnffqhgen uceurghilhhouhhtmecufedttdenucesvcftvggtihhpihgvnhhtshculddquddttddmne cujfgurhepfffhvfevuffkfhggtggujgesghdtreertddtvdenucfhrhhomheprfgrthhr ihgtkhcuufhtvghinhhhrghrughtuceophhssehpkhhsrdhimheqnecuggftrfgrthhtvg hrnhepueektdevtdffveeljeetgfehheeigeekleduvdeffeeghefgledttdehjeelffet necuvehluhhsthgvrhfuihiivgeptdenucfrrghrrghmpehmrghilhhfrhhomhepphhsse hpkhhsrdhimhdpnhgspghrtghpthhtoheptd X-ME-Proxy: Feedback-ID: i197146af:Fastmail Received: by mail.messagingengine.com (Postfix) with ESMTPA; Tue, 30 Jul 2024 03:24:36 -0400 (EDT) Received: by localhost (OpenSMTPD) with ESMTPSA id 7867fbe2 (TLSv1.3:TLS_AES_256_GCM_SHA384:256:NO); Tue, 30 Jul 2024 07:23:09 +0000 (UTC) Date: Tue, 30 Jul 2024 09:24:33 +0200 From: Patrick Steinhardt To: git@vger.kernel.org Cc: Karthik Nayak , Junio C Hamano , Phillip Wood Subject: [PATCH v2 1/5] clang-format: fix indentation width for preprocessor directives Message-ID: References: Precedence: bulk X-Mailing-List: git@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: In [1], we have improved our clang-format configuration to also specify the style for how to indent preprocessor directives. But while we have settled the question of where to put the indentation, either before or after the hash sign, we didn't specify exactly how to indent. With the current configuration, clang-format uses tabs to indent each level of nested preprocessor directives, which is in fact unintentional and never done in our codebase. Instead, we use a mixture of indenting by either one or two spaces, where using a single space is somewhat more common. Adapt our clang-format configuration accordingly by specifying an indentation width of one space. [1]: <20240708092317.267915-1-karthik.188@gmail.com> Signed-off-by: Patrick Steinhardt --- .clang-format | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/.clang-format b/.clang-format index 16fd12253e..0b82f3c776 100644 --- a/.clang-format +++ b/.clang-format @@ -100,11 +100,13 @@ BreakStringLiterals: false # Switch statement body is always indented one level more than case labels. IndentCaseLabels: false -# Indents directives before the hash. +# Indents directives before the hash. Each level uses a single space for +# indentation. # #if FOO -# # include +# # include # #endif IndentPPDirectives: AfterHash +PPIndentWidth: 1 # Don't indent a function definition or declaration if it is wrapped after the # type From patchwork Tue Jul 30 07:24:38 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Patrick Steinhardt X-Patchwork-Id: 13746829 Received: from fhigh2-smtp.messagingengine.com (fhigh2-smtp.messagingengine.com [103.168.172.153]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id C94B6192B60 for ; Tue, 30 Jul 2024 07:24:42 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=103.168.172.153 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1722324284; cv=none; b=bIXb3Ch8Fvr/qiwMw4u0FGJpgWR1ZqD6g6essf261h/2p6bF4lfIHFgkl6WROTv1bQ+jaWIQdUpeDh75F7gfnGcdD2MQGLe4qFAR3cFFviN6CESVMrgI2bCgSxxFjmcONUukg8L+1WLz6im/lpd9PosbeUZn6Kiq5PbJSnCUe4I= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1722324284; c=relaxed/simple; bh=OjjXKcWjboBDwCwS5+M6OsYMG3y361Le7AVNbWjxZSw=; h=Date:From:To:Cc:Subject:Message-ID:References:MIME-Version: Content-Type:Content-Disposition:In-Reply-To; b=QedCbcE6eijkJsxQmfMRy5cOmI78bUdcOHTmNbpKXs+AH2csoG3NxcJtApTr8wi52EBKq9bhmvG1ttxOLFkPKJ3PUhDOgxCHNvVZLYgRysP7bWRjS6DloRLtcec7h/6DXWuEKELFY6NTr5vw0OwdPPepgIh0agkqBuQyiP3MDP4= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=pks.im; spf=pass smtp.mailfrom=pks.im; dkim=pass (2048-bit key) header.d=pks.im header.i=@pks.im header.b=qc/q+Ntg; dkim=pass (2048-bit key) header.d=messagingengine.com header.i=@messagingengine.com header.b=lyiAuCyU; arc=none smtp.client-ip=103.168.172.153 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=pks.im Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=pks.im Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=pks.im header.i=@pks.im header.b="qc/q+Ntg"; dkim=pass (2048-bit key) header.d=messagingengine.com header.i=@messagingengine.com header.b="lyiAuCyU" Received: from compute1.internal (compute1.nyi.internal [10.202.2.41]) by mailfhigh.nyi.internal (Postfix) with ESMTP id B371C1140473; Tue, 30 Jul 2024 03:24:41 -0400 (EDT) Received: from mailfrontend1 ([10.202.2.162]) by compute1.internal (MEProxy); Tue, 30 Jul 2024 03:24:41 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=pks.im; h=cc:cc :content-type:content-type:date:date:from:from:in-reply-to :in-reply-to:message-id:mime-version:references:reply-to:subject :subject:to:to; s=fm3; t=1722324281; x=1722410681; bh=1vaRnmch/F DoeRVASHvedFndINirE+AxeAF13C0T2Pc=; b=qc/q+Ntg80l2Kv1WimwECPfZc6 UW2Qmd1s1DPh/f7jIwxvvSEU/GbOyOGC2tyrVM6Czb1xv+W0GYWR273k1/8Ww6e0 PDrzigeqX7ltWKVDgTAJKsCC4u8EB+f9gOs3HxrtHSxhnDO3DHKtaWRipvMgkI4C bCwj7TeuQ6Glmlkur+I/esUO1qn3n4cc76lLE0ozeHrJ8TDsUPRYHvTkLkg/P62C NrqHtELQ5uQpHEOEdPMfJjsyM67tagybLw9HLx2NOvMtQbQSrsuXPm8WP0JG/TcZ LzySlOrLi2Z2i55Q2v8rZsqwXBp0CF8ptwk9T1MgbEMvFkvQVwAOUgtZoUxQ== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:cc:content-type:content-type:date:date :feedback-id:feedback-id:from:from:in-reply-to:in-reply-to :message-id:mime-version:references:reply-to:subject:subject:to :to:x-me-proxy:x-me-proxy:x-me-sender:x-me-sender:x-sasl-enc; s= fm3; t=1722324281; x=1722410681; bh=1vaRnmch/FDoeRVASHvedFndINir E+AxeAF13C0T2Pc=; b=lyiAuCyUuTb9a28S0gKpjabUYLu3NHMcmnlmHTMhgOY5 qdOgQIWlb65fLIu8Ch3Zb6IHeCcBzkDcR4ZQuSKzCgKlbG7blCnj8suyacO8YSnr SRhC1immnlqjRfRVlNtRWnPaM1nPgSte3VP533iiViCSXH/J2OmlelNN0n3fYhYD H0toN1fKfSKuiB3el5ecGjVtmfpBYDmcRxl8c7Lflw2z01O32UzBAdEEhvigL+H1 GlSIl3BXkP/5jBb9/pAQsZZdAZd25n8h02Xj8e7ghmPZfDEYwq3Pd7CvM/6nK5Jh urCgDH+j9SIypL9GsCnPgKg0Ib5gWrfIm7LZ+Bsqcw== X-ME-Sender: X-ME-Received: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeeftddrjeefgdduvdefucetufdoteggodetrfdotf fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfqfgfvpdfurfetoffkrfgpnffqhgen uceurghilhhouhhtmecufedttdenucesvcftvggtihhpihgvnhhtshculddquddttddmne cujfgurhepfffhvfevuffkfhggtggujgesghdtreertddtvdenucfhrhhomheprfgrthhr ihgtkhcuufhtvghinhhhrghrughtuceophhssehpkhhsrdhimheqnecuggftrfgrthhtvg hrnhepueektdevtdffveeljeetgfehheeigeekleduvdeffeeghefgledttdehjeelffet necuvehluhhsthgvrhfuihiivgeptdenucfrrghrrghmpehmrghilhhfrhhomhepphhsse hpkhhsrdhimhdpnhgspghrtghpthhtoheptd X-ME-Proxy: Feedback-ID: i197146af:Fastmail Received: by mail.messagingengine.com (Postfix) with ESMTPA; Tue, 30 Jul 2024 03:24:40 -0400 (EDT) Received: by localhost (OpenSMTPD) with ESMTPSA id 085e4b6f (TLSv1.3:TLS_AES_256_GCM_SHA384:256:NO); Tue, 30 Jul 2024 07:23:13 +0000 (UTC) Date: Tue, 30 Jul 2024 09:24:38 +0200 From: Patrick Steinhardt To: git@vger.kernel.org Cc: Karthik Nayak , Junio C Hamano , Phillip Wood Subject: [PATCH v2 2/5] Documentation: clarify indentation style for C preprocessor directives Message-ID: References: Precedence: bulk X-Mailing-List: git@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: In the preceding commit, we have settled on using a single space per nesting level to indent preprocessor directives. Clarify our coding guidelines accordingly. Signed-off-by: Patrick Steinhardt --- Documentation/CodingGuidelines | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 1d92b2da03..65fba3b810 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -214,6 +214,16 @@ For C programs: - We use tabs to indent, and interpret tabs as taking up to 8 spaces. + - Nested C preprocessor directives are indented after the hash by one + space per nesting level. + + #if FOO + # include + # if BAR + # include + # endif + #endif + - We try to keep to at most 80 characters per line. - As a Git developer we assume you have a reasonably modern compiler From patchwork Tue Jul 30 07:24:43 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Patrick Steinhardt X-Patchwork-Id: 13746830 Received: from fout5-smtp.messagingengine.com (fout5-smtp.messagingengine.com [103.168.172.148]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 306B6190477 for ; Tue, 30 Jul 2024 07:24:47 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=103.168.172.148 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1722324289; cv=none; b=JEjI2GLo5cplUytT3xPyIgvELc1cdeFZcW53LFzCOmGZ8ToiZuvM609OCKZeyLDr2QudRIV/QNonV88+Ey2+BhvpNGFDEWzjMRZ7Z1t3BPJ2NoGIfmfWR4a96HIa1skghXHLEN5geOAZQeKrrUfO2SmQQbFmlFIBHRgiXlm7Vgg= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1722324289; c=relaxed/simple; bh=MdzWcQ7yHmgLE+L3VaAlFjj5nbR6WZvk5JcXzy7G/yc=; h=Date:From:To:Cc:Subject:Message-ID:References:MIME-Version: Content-Type:Content-Disposition:In-Reply-To; b=n/T3PJXpTqWtEz0SL/SKCoRIAD7W+yOs8NmsT/JJYg2zES2CrBU+Krn9IyudeqdMXfdb+m5tPQwAMXwpwQuKhPCJRmfyVn3aheb1IE6VRVvLuViCp422ht870QjhScq2Q5hBsLaKDKbsdDNqrEOE6v2CiINooiO7750nba/8vjY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=pks.im; spf=pass smtp.mailfrom=pks.im; dkim=pass (2048-bit key) header.d=pks.im header.i=@pks.im header.b=RcZPAePT; dkim=pass (2048-bit key) header.d=messagingengine.com header.i=@messagingengine.com header.b=Zr7XA4cO; arc=none smtp.client-ip=103.168.172.148 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=pks.im Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=pks.im Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=pks.im header.i=@pks.im header.b="RcZPAePT"; dkim=pass (2048-bit key) header.d=messagingengine.com header.i=@messagingengine.com header.b="Zr7XA4cO" Received: from compute3.internal (compute3.nyi.internal [10.202.2.43]) by mailfout.nyi.internal (Postfix) with ESMTP id E71E513807CD; Tue, 30 Jul 2024 03:24:46 -0400 (EDT) Received: from mailfrontend1 ([10.202.2.162]) by compute3.internal (MEProxy); Tue, 30 Jul 2024 03:24:46 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=pks.im; h=cc:cc :content-type:content-type:date:date:from:from:in-reply-to :in-reply-to:message-id:mime-version:references:reply-to:subject :subject:to:to; s=fm3; t=1722324286; x=1722410686; bh=mhueC9fQTn q+qTvOn1oXUeB616GYuRXAaU50UiNcxTE=; b=RcZPAePTbg+azAGq0eLg6sJVAF hPREmCLPq89AWf6eEsp/0T8liRznZFCo8ym1xU9bK8P8rx11KEr4762Hjgz0bTF0 pd45IAx60KZsSGZpTwHY8IrEbNzuOkPk3Eu4q5Mv1qminOOmNoWcwbd5K1H0yco2 SnKY6SHVPKHR9gXHN2eWOgsiXpzA/kOeeHOSzAMVBOBTkBHu8eRGdsebKD5tfD3a Di4uBVbB0gsl4w5o8ZI9TxzlZlFu+4eGssz4yLWbyAfyCfNn+jQfVYLnF9lFAO3+ 9SA0Z2sh6xVva81+WPWv+fTF22TgJGSY2mseT2lHXbZnbT8l+hgskVoR3GtQ== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:cc:content-type:content-type:date:date :feedback-id:feedback-id:from:from:in-reply-to:in-reply-to :message-id:mime-version:references:reply-to:subject:subject:to :to:x-me-proxy:x-me-proxy:x-me-sender:x-me-sender:x-sasl-enc; s= fm3; t=1722324286; x=1722410686; bh=mhueC9fQTnq+qTvOn1oXUeB616GY uRXAaU50UiNcxTE=; b=Zr7XA4cOCYpsZCqKNam27ko6XDvMis6AX0vmFAq6Plzx KsAPyq3WSTe/3QNaiX2sm8AUKIBVDmjfmsIGAIWaBxcemKTVVeNdI8AbcOLtYZlf DakQvh9gWELe4GKHGKwMKKJ2wmthiEpx09jpguPOJIA16tiKKYoOFc2zq9d1jcEi YuwzeqPH59uKrAEriurjZIzTBvme0k95z0ViIR2qkF4QVsqqzZV40u2GPWsSF5Xc YgldOY43Mz88tlFmJGjso7p+HOGL66WPKUL28lbuA+fNgR5iW79T9QmO1cDFfMuB zVmhwr/5vKPftDBsl//xmR6GWVIxBptZm5YuEiNUPA== X-ME-Sender: X-ME-Received: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeeftddrjeefgdduvdefucetufdoteggodetrfdotf fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfqfgfvpdfurfetoffkrfgpnffqhgen uceurghilhhouhhtmecufedttdenucesvcftvggtihhpihgvnhhtshculddquddttddmne cujfgurhepfffhvfevuffkfhggtggujgesghdtreertddtvdenucfhrhhomheprfgrthhr ihgtkhcuufhtvghinhhhrghrughtuceophhssehpkhhsrdhimheqnecuggftrfgrthhtvg hrnhepueektdevtdffveeljeetgfehheeigeekleduvdeffeeghefgledttdehjeelffet necuvehluhhsthgvrhfuihiivgeptdenucfrrghrrghmpehmrghilhhfrhhomhepphhsse hpkhhsrdhimhdpnhgspghrtghpthhtoheptd X-ME-Proxy: Feedback-ID: i197146af:Fastmail Received: by mail.messagingengine.com (Postfix) with ESMTPA; Tue, 30 Jul 2024 03:24:45 -0400 (EDT) Received: by localhost (OpenSMTPD) with ESMTPSA id 412f3b52 (TLSv1.3:TLS_AES_256_GCM_SHA384:256:NO); Tue, 30 Jul 2024 07:23:18 +0000 (UTC) Date: Tue, 30 Jul 2024 09:24:43 +0200 From: Patrick Steinhardt To: git@vger.kernel.org Cc: Karthik Nayak , Junio C Hamano , Phillip Wood Subject: [PATCH v2 3/5] Documentation: document naming schema for structs and their functions Message-ID: <25f73b970dcf8b1d1e7629f75c157ee02cd10809.1722323818.git.ps@pks.im> References: Precedence: bulk X-Mailing-List: git@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: We nowadays have a proper mishmash of struct-related functions that are called `_` (e.g. `clear_prio_queue()`) versus functions that are called `_` (e.g. `strbuf_clear()`). While the former style may be easier to tie into a spoken conversation, most of our communication happens in text anyway. Furthermore, prefixing functions with the name of the structure they operate on makes it way easier to group them together, see which functions are related, and will also help folks who are using code completion. Let's thus settle on one style, namely the one where functions start with the name of the structure they operate on. Signed-off-by: Patrick Steinhardt --- Documentation/CodingGuidelines | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 65fba3b810..a6a1ede204 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -541,6 +541,25 @@ For C programs: use your own debugger and arguments. Example: `GIT_DEBUGGER="ddd --gdb" ./bin-wrappers/git log` (See `wrap-for-bin.sh`.) + - The primary data structure that a subsystem 'S' deals with is called + `struct S`. Functions that operate on `struct S` are named + `S_()` and should generally receive a pointer to `struct S` as + first parameter. E.g. + + struct strbuf; + + void strbuf_add(struct strbuf *buf, ...); + + void strbuf_reset(struct strbuf *buf); + + is preferred over: + + struct strbuf; + + void add_string(struct strbuf *buf, ...); + + void reset_strbuf(struct strbuf *buf); + For Perl programs: - Most of the C guidelines above apply. From patchwork Tue Jul 30 07:24:47 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Patrick Steinhardt X-Patchwork-Id: 13746831 Received: from fhigh2-smtp.messagingengine.com (fhigh2-smtp.messagingengine.com [103.168.172.153]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 7268A190477 for ; Tue, 30 Jul 2024 07:24:52 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=103.168.172.153 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1722324294; cv=none; b=XhX11iCcOtD/eljfwlTv+PMb59wDCApmcZNdMcUgdgl18DYpU0lihrcyOGWZsNa6RlzU9V7iQAqIKd+MhCaYvGzOSOqdtCLaKmd5Ywn0SwyTgpvhQfQSyP2no/J34yEjZAYwCZSYTBM16kntWmlApwO2p5pUgdiDVpF757WgRjw= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1722324294; c=relaxed/simple; bh=0wOwKY6pmmovLtDwmesUlW12sJ3IuWTbD4IEYQOZL0s=; h=Date:From:To:Cc:Subject:Message-ID:References:MIME-Version: Content-Type:Content-Disposition:In-Reply-To; b=tqiuEBmCMyImsw2tKMuKbB7/lfK8mh29yFJ44es6UTfzqJR60Bg+SzvLF1lAqFBGKJlvmXRL9+MftHXs/CFzvt8tcIOGf19ksGgAyJu5nljoE0Afb0+AjPS45P8qt3vCSCL8tHfhdyNTiLGZiWBsyNVgMVq4IKUAHKSChlEThc4= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=pks.im; spf=pass smtp.mailfrom=pks.im; dkim=pass (2048-bit key) header.d=pks.im header.i=@pks.im header.b=c16n7EkU; dkim=pass (2048-bit key) header.d=messagingengine.com header.i=@messagingengine.com header.b=ITzyMi5X; arc=none smtp.client-ip=103.168.172.153 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=pks.im Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=pks.im Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=pks.im header.i=@pks.im header.b="c16n7EkU"; dkim=pass (2048-bit key) header.d=messagingengine.com header.i=@messagingengine.com header.b="ITzyMi5X" Received: from compute3.internal (compute3.nyi.internal [10.202.2.43]) by mailfhigh.nyi.internal (Postfix) with ESMTP id 72F6C1140383; Tue, 30 Jul 2024 03:24:51 -0400 (EDT) Received: from mailfrontend1 ([10.202.2.162]) by compute3.internal (MEProxy); Tue, 30 Jul 2024 03:24:51 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=pks.im; h=cc:cc :content-type:content-type:date:date:from:from:in-reply-to :in-reply-to:message-id:mime-version:references:reply-to:subject :subject:to:to; s=fm3; t=1722324291; x=1722410691; bh=NI0+O5P8BW 8w7bPWZJOGpuerfzpW/wQ1/fFJ2mtdWF8=; b=c16n7EkUEU2nTUOJu92QCdX2/z FTtrcsQYyCuAB+OG1nwze3eWgUPuvBxd0+HzYxsUDH9AUC0q6VQLCXWq5MxVvZ8J /swxeRYwbESztCwAjycAXAdSYFXxa2b6IS3a1lFbtKIw7QodRy5HGIFfSAqmJ96z Nz4yVXyQzoigq55hR4Ydkuw7gpnJHk08QPRJXZwD9gWZaJFy5+CHGA4hTNHP74BD uo3FfNwgD6rBKaAihSmw+iBRjxJMN2uXCuq6bN4eTCmm6ZQrz6KMd6Vaxk04tKJ5 KfSvxm4E5+EKx5zcxA2P+zYlCLZmpqJiB05JDJXU204AFmvpKBDH4seKl3YQ== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:cc:content-type:content-type:date:date :feedback-id:feedback-id:from:from:in-reply-to:in-reply-to :message-id:mime-version:references:reply-to:subject:subject:to :to:x-me-proxy:x-me-proxy:x-me-sender:x-me-sender:x-sasl-enc; s= fm3; t=1722324291; x=1722410691; bh=NI0+O5P8BW8w7bPWZJOGpuerfzpW /wQ1/fFJ2mtdWF8=; b=ITzyMi5XNwqeHfYKaJmARS+5tuJbCl07c2DUUGe3jCWx fN8WjLeW/2x8rPI4BTpKq23qZOVb+9LaaSkUzhhARPC+jEPnelHYmCPljXuYcy1q 66b7ZdYGeV89fvFxY1QfWBNFn9XSgc/ywVRoyOIC3UFtCSr2YZLVBKT0QXpRa7+4 mD3GJJsTxZiK1BslPSW62FqFpAaZKlkuBaOTDQHbGLUjoGkqy6dllVm4KbZW6skv s7GOonHyza/KfNCY8RsMyzB7rL0rVz06+Q3rnbBKKiZo6UNvJVpbOgoxctqD7w5n 07t4un87Twor4J3wuOGBoxtaD2oS9oo40VCXv5hQhg== X-ME-Sender: X-ME-Received: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeeftddrjeefgdduvdefucetufdoteggodetrfdotf fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfqfgfvpdfurfetoffkrfgpnffqhgen uceurghilhhouhhtmecufedttdenucesvcftvggtihhpihgvnhhtshculddquddttddmne cujfgurhepfffhvfevuffkfhggtggujgesghdtreertddtvdenucfhrhhomheprfgrthhr ihgtkhcuufhtvghinhhhrghrughtuceophhssehpkhhsrdhimheqnecuggftrfgrthhtvg hrnhepueektdevtdffveeljeetgfehheeigeekleduvdeffeeghefgledttdehjeelffet necuvehluhhsthgvrhfuihiivgepudenucfrrghrrghmpehmrghilhhfrhhomhepphhsse hpkhhsrdhimhdpnhgspghrtghpthhtoheptd X-ME-Proxy: Feedback-ID: i197146af:Fastmail Received: by mail.messagingengine.com (Postfix) with ESMTPA; Tue, 30 Jul 2024 03:24:50 -0400 (EDT) Received: by localhost (OpenSMTPD) with ESMTPSA id 313b4be0 (TLSv1.3:TLS_AES_256_GCM_SHA384:256:NO); Tue, 30 Jul 2024 07:23:23 +0000 (UTC) Date: Tue, 30 Jul 2024 09:24:47 +0200 From: Patrick Steinhardt To: git@vger.kernel.org Cc: Karthik Nayak , Junio C Hamano , Phillip Wood Subject: [PATCH v2 4/5] Documentation: document idiomatic function names Message-ID: References: Precedence: bulk X-Mailing-List: git@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: We semi-regularly have discussions around whether a function shall be named `S_release()`, `S_clear()` or `S_free()`. Indeed, it may not be obvious which of these is preferable as we never really defined what each of these variants means exactly. Carve out a space where we can add idiomatic names for common functions in our coding guidelines and define each of those functions. Like this, we can get to a shared understanding of their respective semantics and can easily point towards our style guide in future discussions such that our codebase becomes more consistent over time. Note that the intent is not to rename all functions which violate these semantics right away. Rather, the intent is to slowly converge towards a common style over time. Signed-off-by: Patrick Steinhardt --- Documentation/CodingGuidelines | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index a6a1ede204..b63a8f9a44 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -560,6 +560,23 @@ For C programs: void reset_strbuf(struct strbuf *buf); + - There are several common idiomatic names for functions performing + specific tasks on a structure `S`: + + - `S_init()` initializes a structure without allocating the + structure itself. + + - `S_release()` releases a structure's contents without freeing the + structure. + + - `S_clear()` is equivalent to `S_release()` followed by `S_init()` + such that the structure is directly usable after clearing it. When + `S_clear()` is provided, `S_init()` shall not allocate resources + that need to be released again. + + - `S_free()` releases a structure's contents and frees the + structure. + For Perl programs: - Most of the C guidelines above apply. From patchwork Tue Jul 30 07:24:52 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Patrick Steinhardt X-Patchwork-Id: 13746832 Received: from fout5-smtp.messagingengine.com (fout5-smtp.messagingengine.com [103.168.172.148]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 77DEE18629C for ; Tue, 30 Jul 2024 07:24:57 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=103.168.172.148 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1722324299; cv=none; b=Y4XYUY7KCAHALrhcgsbCTtg9s2M1F83JlSW8KMnVVDdTt7e4uE0VVmPWKgyl+XaixZGjbVaiLStgpc18wUQUHKn/YnPg6OuH0MgnLUybFAxM9J0C82nl0IfYlmTrVio5G+S24+gQbCNigrXUBgh6kAM1aCIeDqBcQmsS4NUEmB0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1722324299; c=relaxed/simple; bh=tPGQT7LKOAWg0azvSP33SVBEEeFyLUdBL5/yzm+7PjQ=; h=Date:From:To:Cc:Subject:Message-ID:References:MIME-Version: Content-Type:Content-Disposition:In-Reply-To; b=TP88sTDzUWXDX2K2jfRDRha3bOOMJJjZSP6/DSzc2kz9pRopkUOqbtP9K0+S56nIlENwfh7Uk8gtn0ZHJ1MSK2Wkogg1uysC0F6EdQlzsy6pOZBfUdtvw0UjYVvw41rajVY7fVRZUoRx22LGxOvwjf0E5wYs9b0FNKUO5WbCIDE= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=pks.im; spf=pass smtp.mailfrom=pks.im; dkim=pass (2048-bit key) header.d=pks.im header.i=@pks.im header.b=cdwjmP8k; dkim=pass (2048-bit key) header.d=messagingengine.com header.i=@messagingengine.com header.b=HpDIqT+1; arc=none smtp.client-ip=103.168.172.148 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=pks.im Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=pks.im Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=pks.im header.i=@pks.im header.b="cdwjmP8k"; dkim=pass (2048-bit key) header.d=messagingengine.com header.i=@messagingengine.com header.b="HpDIqT+1" Received: from compute3.internal (compute3.nyi.internal [10.202.2.43]) by mailfout.nyi.internal (Postfix) with ESMTP id A1D3113807C3; Tue, 30 Jul 2024 03:24:56 -0400 (EDT) Received: from mailfrontend1 ([10.202.2.162]) by compute3.internal (MEProxy); Tue, 30 Jul 2024 03:24:56 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=pks.im; h=cc:cc :content-type:content-type:date:date:from:from:in-reply-to :in-reply-to:message-id:mime-version:references:reply-to:subject :subject:to:to; s=fm3; t=1722324296; x=1722410696; bh=8c5ENsvlJ9 Q6luQQWn2Prawu9Nfn6IwX/TW4b5XePWk=; b=cdwjmP8kv4dCzZUXoffKR6n3ru VPDeACSvuX8qylEIw5zGEsvkKqPd3Fbpaf37SY3iZvr6ZH9+miLsaHx6xncMnC3o ZvRK6joJQ/uYgr9AAaknc6Coc4htJGm25BQfZMqvrrjR55xv8JqoqFI76KcUCeYi mYUdZ3Vjxz5TdrFsDpnfrosgDkLHc4/sG39pk7wXJuYVUhzaFanx0FYo5Kg7HyMi JO8s2V0FPbOzJ2urFU/2IlJudkx414eHC1mG1It1pTeE4sUXx6exaX6510Jd3AeU vPhAXoswjE/lViTCTdTVH1s0+0GKLAQPgP5Dl/5cu28ewSmknN8F1eEMme7A== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:cc:content-type:content-type:date:date :feedback-id:feedback-id:from:from:in-reply-to:in-reply-to :message-id:mime-version:references:reply-to:subject:subject:to :to:x-me-proxy:x-me-proxy:x-me-sender:x-me-sender:x-sasl-enc; s= fm3; t=1722324296; x=1722410696; bh=8c5ENsvlJ9Q6luQQWn2Prawu9Nfn 6IwX/TW4b5XePWk=; b=HpDIqT+1yeDzjwtndCJmb6G0NThmYJ1woS83na9CZ6zL 4xMoIskJhn6y+Fdozl+V2oYpCDqNiZw+sz3H6aszBKP+H5yL4OFgkgeUMscFxk/D D00GT1MfiFrMdPlCpDpb4P1beF0tM99EdnnLRAk7dNezJXOrxcBdHX8ME7sg2yx+ R5t75WfoELvdR7ACf7M0ZZylDi6n08T6JYYB9wmpSLLpW2Z2ojhLogSD2dcB32a6 +rAnltrijwOHyprnd6gamzY5n5v17Tfr5JC69kjFvCHouKH8x4M8yCCA37cfJTJC ZdgWWOtXcXXw9mcSutD+Ph7JJTTIgxUIEr/XLSA1qg== X-ME-Sender: X-ME-Received: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeeftddrjeefgdduvdefucetufdoteggodetrfdotf fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfqfgfvpdfurfetoffkrfgpnffqhgen uceurghilhhouhhtmecufedttdenucesvcftvggtihhpihgvnhhtshculddquddttddmne cujfgurhepfffhvfevuffkfhggtggujgesghdtreertddtvdenucfhrhhomheprfgrthhr ihgtkhcuufhtvghinhhhrghrughtuceophhssehpkhhsrdhimheqnecuggftrfgrthhtvg hrnhepueektdevtdffveeljeetgfehheeigeekleduvdeffeeghefgledttdehjeelffet necuvehluhhsthgvrhfuihiivgepvdenucfrrghrrghmpehmrghilhhfrhhomhepphhsse hpkhhsrdhimhdpnhgspghrtghpthhtoheptd X-ME-Proxy: Feedback-ID: i197146af:Fastmail Received: by mail.messagingengine.com (Postfix) with ESMTPA; Tue, 30 Jul 2024 03:24:55 -0400 (EDT) Received: by localhost (OpenSMTPD) with ESMTPSA id d269a42c (TLSv1.3:TLS_AES_256_GCM_SHA384:256:NO); Tue, 30 Jul 2024 07:23:27 +0000 (UTC) Date: Tue, 30 Jul 2024 09:24:52 +0200 From: Patrick Steinhardt To: git@vger.kernel.org Cc: Karthik Nayak , Junio C Hamano , Phillip Wood Subject: [PATCH v2 5/5] Documentation: consistently use spaces inside initializers Message-ID: <8789323ac770e00707df4708994f7767bf57b00f.1722323818.git.ps@pks.im> References: Precedence: bulk X-Mailing-List: git@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: Our coding guide is inconsistent with how it uses spaces inside of initializers (`struct foo bar = { something }`). While we mostly carry the space between open and closing braces and the initialized members, in one case we don't. Fix this one instance such that we consistently carry the space. This is also consistent with how clang-format formats such initializers. Signed-off-by: Patrick Steinhardt --- Documentation/CodingGuidelines | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index b63a8f9a44..3daa1f82bb 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -244,7 +244,7 @@ For C programs: . since around 2007 with 2b6854c863a, we have been using initializer elements which are not computable at load time. E.g.: - const char *args[] = {"constant", variable, NULL}; + const char *args[] = { "constant", variable, NULL }; . since early 2012 with e1327023ea, we have been using an enum definition whose last element is followed by a comma. This, like