Re: [PATCH v6 1/4] last-modified: new subcommand to show when files were last modified

> Patrick Steinhardt <ps@pks.im> writes:
> 
> >> > +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