Re: [PATCH v6 1/4] last-modified: new subcommand to show when files were last modified
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Aug 1, 2025, 17:06 UTC
- Message-ID
- <xmqq7bznm0nk.fsf@gitster.g>
- In-Reply-To
- <aIyVft9PdlorttzZ@pks.im>
Patrick Steinhardt <ps@pks.im> writes:
Show 11 quoted lines
>> > +static void last_modified_release(struct last_modified *lm) >> >> I think these days we tend to name those functions using "clear" >> instead of "release" > > It actually depends: if the structure can be immediately reused > afterwards without requiring another reinit it would be caller "clear" > indeed. On the other hand, if we only release memory it's "release". > > I think this function here falls into the latter category, so it's > correctly named.
Given that even a long-time contributor gets confused (including me, who needed to see where we documented this for our developers), perhaps a clarification patch is in order?
--- >8 --- Subject: CodingGuidelines: clarify that S_release() does not reinitialize
In the section for naming various API functions, the fact that S_release() only releases the resources without preparing the structure for immediate reuse becomes only apparent when you readentries for S_release() and S_clear().
Clarify the description of S_release() a bit to make the entry self sufficient.
Signed-off-by: Junio C Hamano <gitster@pobox.com> --- Documentation/CodingGuidelines | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-)
diff --git c/Documentation/CodingGuidelines w/Documentation/CodingGuidelines index c1046abfb7..76ec6268f2 100644 --- c/Documentation/CodingGuidelines +++ w/Documentation/CodingGuidelines @@ -610,8 +610,9 @@ For C programs: - `S_init()` initializes a structure without allocating the structure itself. - - `S_release()` releases a structure's contents without freeing the - structure. + - `S_release()` releases a structure's contents without reinitializing + the structure for immediate reuse, and without freeing the structure + itself. - `S_clear()` is equivalent to `S_release()` followed by `S_init()` such that the structure is directly usable after clearing it. When