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.