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.