From patchwork Wed Jul 24 11:05:12 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Patrick Steinhardt X-Patchwork-Id: 13740849 Received: from fout6-smtp.messagingengine.com (fout6-smtp.messagingengine.com [103.168.172.149]) (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 8EF5F15696E for ; Wed, 24 Jul 2024 11:05:18 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=103.168.172.149 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1721819120; cv=none; b=QSTx38fUHTDSRiLeEoafBBHuwp4diDwmm1ueHEzv2mIrHl+18FAbss8FoldzUs1rb9/WaTAsVTJqT22XJutz9Y2Vat5VrtM0OXc9gWs5TaJ6HT+c9bjOlrvCyP7Liw3ug8PLZlOZ3nP9Mc7la5jgB8AdWWRIy6+YVpfC5Z7JF9w= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1721819120; c=relaxed/simple; bh=oLYbltn6mvrvcbiPRWNGwoOyEgIyXNiHO5yNUQ3UFWM=; h=Date:From:To:Cc:Subject:Message-ID:References:MIME-Version: Content-Type:Content-Disposition:In-Reply-To; b=Rf2YtXDa5A4p4zp83vTCvfl1mBWc6JldHNUEMbH1P8v6oKYsFJRy27bIZcANdrZGuGfbCmONUeqycZ04FUli8fRRf2sHmDSBAcfvEDgO9DLjc/9baxXRU3/tPj0zKvPvMjKsoMHrN+PKYTtMn23LO7zoj7TK0eT9CiCVjWz1CvU= 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=VDK8Qhxd; dkim=pass (2048-bit key) header.d=messagingengine.com header.i=@messagingengine.com header.b=c9OCZfuc; arc=none smtp.client-ip=103.168.172.149 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="VDK8Qhxd"; dkim=pass (2048-bit key) header.d=messagingengine.com header.i=@messagingengine.com header.b="c9OCZfuc" Received: from compute2.internal (compute2.nyi.internal [10.202.2.46]) by mailfout.nyi.internal (Postfix) with ESMTP id 4A07A1380677; Wed, 24 Jul 2024 07:05:16 -0400 (EDT) Received: from mailfrontend2 ([10.202.2.163]) by compute2.internal (MEProxy); Wed, 24 Jul 2024 07:05:16 -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=1721819116; x=1721905516; bh=lfF4jDyM6a a9xbdYq7HVSN3dQzqpQFMbIiUfAu+t+Z8=; b=VDK8Qhxdev1qw1U7nrqbBwVAtv kir3vFLMfbRcu1kDKJKeXgyfgthQLWb/au1n9yKx0slYLvH65CmRZqLGZE6/sf/R HxBqNyavS4eamE0KuGf4fQuU0Qs4vlPuDhruWShs3npnfaVTEeQqMglWJBKhYQy/ VsKRCUmVv1fP/MxNTqa1cgEW6f48LoumSmZeodJc3M8ocVFbr5r4OqwRJANgdd1L e9Ldt1NE703++ATmeRXEKPcg5q8FC4tfbKRbOQ78gMhFTv0Xltswo2qh7ukmrF+X 8UjcROuxKo5mJew4B2L4Wi7lszzhO/SaIHt6+iRJ2Y/ixhbxAXhILO0yP2Cg== 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=1721819116; x=1721905516; bh=lfF4jDyM6aa9xbdYq7HVSN3dQzqp QFMbIiUfAu+t+Z8=; b=c9OCZfuc+sbonixw1FUYYaAMISUJ5O+MDjsTzOcXzj2b mLL39ILqvJ0PwUv55/k1z/wisKfRO+iJypLoURcN4zUOc/QzWKOS0VYge0QSsTvJ uJDxlLgt6gIW1Hjuoo7uydf3ZppezUyAC3fmWzVuYJHDguxl2tLauEuqykHvlOFf eV4a4d3mB4QJyeie1I1lhIIVj0gFh9nAo/k506KgMJlbfOjf8opREn3lSRr+rHFy jhZ8fI24I7qydIhsmZ/cgzhu9EciZzbt3/36bHg82aIvdUQGSkkwz2NgvHspe2fH fVBrG+crFPRn91XI6jM/52sG9i6C6sVv+qPiz0kmCw== X-ME-Sender: X-ME-Received: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeeftddriedugdefjecutefuodetggdotefrodftvf curfhrohhfihhlvgemucfhrghsthforghilhdpqfgfvfdpuffrtefokffrpgfnqfghnecu uegrihhlohhuthemuceftddtnecusecvtfgvtghiphhivghnthhsucdlqddutddtmdenuc fjughrpeffhffvvefukfhfgggtuggjsehgtderredttddvnecuhfhrohhmpefrrghtrhhi tghkucfuthgvihhnhhgrrhguthcuoehpshesphhkshdrihhmqeenucggtffrrghtthgvrh hnpeeiveektdfggfeluefgvdelvdeftdfhgeeugeefveejleeufeekgeefffehgfelgfen ucffohhmrghinhepkhgvrhhnvghlrdhorhhgnecuvehluhhsthgvrhfuihiivgeptdenuc frrghrrghmpehmrghilhhfrhhomhepphhssehpkhhsrdhimhdpnhgspghrtghpthhtohep td X-ME-Proxy: Feedback-ID: i197146af:Fastmail Received: by mail.messagingengine.com (Postfix) with ESMTPA; Wed, 24 Jul 2024 07:05:15 -0400 (EDT) Received: by localhost (OpenSMTPD) with ESMTPSA id 1c9a0c52 (TLSv1.3:TLS_AES_256_GCM_SHA384:256:NO); Wed, 24 Jul 2024 11:03:59 +0000 (UTC) Date: Wed, 24 Jul 2024 13:05:12 +0200 From: Patrick Steinhardt To: git@vger.kernel.org Cc: Karthik Nayak Subject: [PATCH 1/3] Documentation: clarify indentation style for C preprocessor directives Message-ID: <64e0b449936a6828ead98438d621f7e7684546c8.1721818488.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: There has recently been some discussion around how C preprocessor directives shall be indented [1]. This discussion was settled towards indenting after the hash by two spaces [2]. Document it as such. [1]: https://lore.kernel.org/all/xmqqwmmm1bw6.fsf@gitster.g/ [2]: https://lore.kernel.org/all/20240708092317.267915-2-karthik.188@gmail.com/ Signed-off-by: Patrick Steinhardt --- Documentation/CodingGuidelines | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 1d92b2da03..1d09384f28 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 two + spaces 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 Wed Jul 24 11:05:17 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Patrick Steinhardt X-Patchwork-Id: 13740850 Received: from fout6-smtp.messagingengine.com (fout6-smtp.messagingengine.com [103.168.172.149]) (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 279BF1C6A3 for ; Wed, 24 Jul 2024 11:05:22 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=103.168.172.149 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1721819125; cv=none; b=pMhhhIUgdWSTWxiDkMFwWIJ2gI/rUO4TWi+rw3u/lyNlvLzogKfMLNmpthFUf9mbRZn/JotvduKorb3vs3fbwGU3RJDWna+Vn1OM3/AK8bXnR56DdLtAVl4eL0yl5Bn/TQzNnT6uWjJffXrV3NdldzH0d5o6sqwGkICGENhcUYA= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1721819125; c=relaxed/simple; bh=nS55w214nVXTD2VVcf8dRf87QmsiHHFywkqeiqpZ4TE=; h=Date:From:To:Cc:Subject:Message-ID:References:MIME-Version: Content-Type:Content-Disposition:In-Reply-To; b=KrlLFPKBv8wCUMhDN7s9DcHN5Q29LdIfLbjRVIf8Rni2M53L5ZDUdfN8ziqrYh1klZSIuMpU6eNV1hBCAaRCDrAHjPR5493EbH/3Rfj7McGNorp8k34lrYz30X44iwibeEpoLkSzUsm42rdGQmUJMV16lES5Mwct0014XUpyFCI= 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=KbFV2uPU; dkim=pass (2048-bit key) header.d=messagingengine.com header.i=@messagingengine.com header.b=XNV9UCR0; arc=none smtp.client-ip=103.168.172.149 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="KbFV2uPU"; dkim=pass (2048-bit key) header.d=messagingengine.com header.i=@messagingengine.com header.b="XNV9UCR0" Received: from compute2.internal (compute2.nyi.internal [10.202.2.46]) by mailfout.nyi.internal (Postfix) with ESMTP id 9FEFE138067A; Wed, 24 Jul 2024 07:05:21 -0400 (EDT) Received: from mailfrontend2 ([10.202.2.163]) by compute2.internal (MEProxy); Wed, 24 Jul 2024 07:05:21 -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=1721819121; x=1721905521; bh=RETWbb3Yig 2FdC+intxx2ez18VPRt/+H2leylH3CDTk=; b=KbFV2uPUAThsk/gMW8cs3eZ3W5 zvSQ5x9GRuAzd3v+m3+SJfmmmhZpVmOcIakzb0PM+bg8LgipMHCuF2EI3wsYl/XT EwhyYCwazlLOF9wXfOjjPJpYgjUM8QS6g4m4Cx13gxuIt3Di896FD39+9Fpg5Lck 5q78sdgyWeHYSfQtkqsYIEmp3GHEz0rBx4bpKJ3N7P48d7ww0y4RWUjHQUdSDtg+ t4vf8Wc3y/mi9Ke6wQfpz2s6AtSjtkYps/FD0m78LEK2vh+G71PQlUn/Uj2EVbhz gFHdJMhvoAeQErIvhmCosK2L7xZXLU2/Njqp7f8rcxUYRfRhA69kI3o6oyeA== 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=1721819121; x=1721905521; bh=RETWbb3Yig2FdC+intxx2ez18VPR t/+H2leylH3CDTk=; b=XNV9UCR0JJKJJmT4uV69bB0VShAAfMVvk9qNvQySwKID OLszP1s4xpCnwFvGUEFbHnFBWI7DS8iOttq4zHAh5qTT4U3jdfZ6OJSTv7j3AMTo bHRW+dCe/6+1fkebv6N8n37zGhts/bQB8E7Z3CGUakEW3zd2xxSlKf2bKF7V3Z/L Y52llPuFMBOuoS3nELNSnoHNPS06mJwP88Slfg2TjXv5ScvOYxdXP9etZvwG+bKQ bZqW1ZN5a0T4WFP10RdfIZidZrnj8yMUAjVO59Zn87qKzEMf3gxrid8FW+l5Oo5/ D08obn2sfMOgbILvL8ipabkVZOvuscNU/CNCrl3SSQ== X-ME-Sender: X-ME-Received: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeeftddriedugdefjecutefuodetggdotefrodftvf curfhrohhfihhlvgemucfhrghsthforghilhdpqfgfvfdpuffrtefokffrpgfnqfghnecu uegrihhlohhuthemuceftddtnecusecvtfgvtghiphhivghnthhsucdlqddutddtmdenuc fjughrpeffhffvvefukfhfgggtuggjsehgtderredttddvnecuhfhrohhmpefrrghtrhhi tghkucfuthgvihhnhhgrrhguthcuoehpshesphhkshdrihhmqeenucggtffrrghtthgvrh hnpeeukedtvedtffevleejtefgheehieegkeeluddvfeefgeehgfeltddtheejleffteen ucevlhhushhtvghrufhiiigvpedtnecurfgrrhgrmhepmhgrihhlfhhrohhmpehpshesph hkshdrihhmpdhnsggprhgtphhtthhopedt X-ME-Proxy: Feedback-ID: i197146af:Fastmail Received: by mail.messagingengine.com (Postfix) with ESMTPA; Wed, 24 Jul 2024 07:05:20 -0400 (EDT) Received: by localhost (OpenSMTPD) with ESMTPSA id 99a5a101 (TLSv1.3:TLS_AES_256_GCM_SHA384:256:NO); Wed, 24 Jul 2024 11:04:04 +0000 (UTC) Date: Wed, 24 Jul 2024 13:05:17 +0200 From: Patrick Steinhardt To: git@vger.kernel.org Cc: Karthik Nayak Subject: [PATCH 2/3] Documentation: document naming schema for struct-related functions Message-ID: <7f07bf1f3beee2f74a3572d2b9a8d28b6535053e.1721818488.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 1d09384f28..34fcbcb5a4 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`.) + - Functions that operate on a specific structure and which are used by + other subsystems shall be named after the structure. The function + name should start with the name of the structure followed by a verb. + 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 Wed Jul 24 11:05:22 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Patrick Steinhardt X-Patchwork-Id: 13740851 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 E2713156F48 for ; Wed, 24 Jul 2024 11:05:26 +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=1721819128; cv=none; b=S3/R9Q6jHEwrFiL+0wZnIgIUjdOlCPGLipQHrM5k7HiuUSfAJvATHYc+fG39mTRQxGhx0zaY8bpTAkIPa8f42PFenWFp3Z+GUrMdD5nKoQOYXnrMcluvvTKwmNhT92ratzlwcoPQQ8kDCEJbDn8jXr0ZDcTrRqXAy6cw22HI8QY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1721819128; c=relaxed/simple; bh=egUvbGY+ME57I0AcHEgBfXxcx008Y4PnUammvkuHHbk=; h=Date:From:To:Cc:Subject:Message-ID:References:MIME-Version: Content-Type:Content-Disposition:In-Reply-To; b=WI4y2+6UMDkFGFRRBRwFPSNiAkfBZ+KkCz2faKroyOTk5NfuYwktxuJwio6mc5IFknOUXGt/dIDgeH4hcaxnNQBvnEAQnLjSFeqAi/8EMKIOjrLVwFrTka+WK1LobletTVvP6uz6ddZqZNBcTZkispctYd6DoIgJna9ViFgFzZk= 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=DIzFTxmc; dkim=pass (2048-bit key) header.d=messagingengine.com header.i=@messagingengine.com header.b=JI8GKDNW; 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="DIzFTxmc"; dkim=pass (2048-bit key) header.d=messagingengine.com header.i=@messagingengine.com header.b="JI8GKDNW" Received: from compute8.internal (compute8.nyi.internal [10.202.2.227]) by mailfhigh.nyi.internal (Postfix) with ESMTP id 9B2C71140256; Wed, 24 Jul 2024 07:05:25 -0400 (EDT) Received: from mailfrontend2 ([10.202.2.163]) by compute8.internal (MEProxy); Wed, 24 Jul 2024 07:05:25 -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=1721819125; x=1721905525; bh=VkDrViGblX xKU5Kqnj1AFzTsw1oEgKpqoeaGw2/8Cq8=; b=DIzFTxmc0PnlPY9Q5lNjEHPZrb ZWns10MLxVFHFEF7+2KWiC7n2uCd43ybprG8TLNzwQd+2sMy9q2tZIDyyMOvUtZx vrUTsaqSCU+mr8InZu2rpj+oKvP2PeoF/LkP963+/w3+5jlkFJShhsRj60E6alxV 7JoOIv5I+BKfjXjKQi5YYWXvaqYvGwej5dgPmxJcZsTINgvKkriq6z+HTZyJtskt mLxUdOVi+nqGVWwt18+/j4FCWt2w3iq6O3oCEYmgIvY3pvaJ4PCc5edVCdglN9XC dW1M6UJn+Ib19imtkHQhaD96hAKlwQSoE1DC2UKpUJmSn+gpoDgLi/q9IAHg== 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=1721819125; x=1721905525; bh=VkDrViGblXxKU5Kqnj1AFzTsw1oE gKpqoeaGw2/8Cq8=; b=JI8GKDNWRTvXy82mRsFALKqMNdxwJhqzHRpodNDjEePz FUosq+qvMUEl3xb/1K9zi8H3L8Ox32BrwggeJY2lC7lkgTQ6FBYx0g8hQRtOyjUh T5P3yWmAxdgsrySJS98Pg2jGvICdYxy2ON/FPfX/E1TPVcoHKZoXUal9orTEb9UA +lj4jy+eSzcbTdP0hmsYUDZ2xhKK8VrQKPA1EJuB7bHHZAslrQd/XYRg3S1AyPFQ Hgs6bes6uHi9fyGQKGEsfanWyZqyPAmnvUUsX9lnr2YTaO3r8N85VhY5mERasM/4 23UPSVPGEYxY/TGnEhQ7xp764AUCiLJmGyHsPZIrzA== X-ME-Sender: X-ME-Received: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeeftddriedugdefiecutefuodetggdotefrodftvf curfhrohhfihhlvgemucfhrghsthforghilhdpqfgfvfdpuffrtefokffrpgfnqfghnecu uegrihhlohhuthemuceftddtnecusecvtfgvtghiphhivghnthhsucdlqddutddtmdenuc fjughrpeffhffvvefukfhfgggtuggjsehgtderredttddvnecuhfhrohhmpefrrghtrhhi tghkucfuthgvihhnhhgrrhguthcuoehpshesphhkshdrihhmqeenucggtffrrghtthgvrh hnpeeukedtvedtffevleejtefgheehieegkeeluddvfeefgeehgfeltddtheejleffteen ucevlhhushhtvghrufhiiigvpedtnecurfgrrhgrmhepmhgrihhlfhhrohhmpehpshesph hkshdrihhmpdhnsggprhgtphhtthhopedt X-ME-Proxy: Feedback-ID: i197146af:Fastmail Received: by mail.messagingengine.com (Postfix) with ESMTPA; Wed, 24 Jul 2024 07:05:24 -0400 (EDT) Received: by localhost (OpenSMTPD) with ESMTPSA id f93409d3 (TLSv1.3:TLS_AES_256_GCM_SHA384:256:NO); Wed, 24 Jul 2024 11:04:08 +0000 (UTC) Date: Wed, 24 Jul 2024 13:05:22 +0200 From: Patrick Steinhardt To: git@vger.kernel.org Cc: Karthik Nayak Subject: [PATCH 3/3] Documentation: document difference between release and free Message-ID: <5e1de3c3159968e897a83c05dae5e8504d37a16c.1721818488.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 semi-regularly have discussions around whether a function shall be named `release()` or `free()`. For most of the part we use these two terminologies quite consistently though: - `release()` only frees internal state of a structure, whereas the structure itself is not free'd. - `free()` frees both internal state and the structure itself. Carve out a space where we can add idiomatic names for common functions in our coding guidelines. This space can get extended in the future when we feel the need to document more idiomatic names. Signed-off-by: Patrick Steinhardt --- Documentation/CodingGuidelines | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 34fcbcb5a4..ace4c4ad0c 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -560,6 +560,18 @@ For C programs: void reset_strbuf(struct strbuf *buf); + - There are several common idiomatic names for functions performing + specific tasks on structures: + + - `_init()` initializes a structure without allocating the + structure itself. + + - `_release()` releases a structure's contents without + freeing the structure. + + - `_free()` releases a structure's contents and frees the + structure. + For Perl programs: - Most of the C guidelines above apply.