Patrick Steinhardt <ps@xxxxxx> writes: > 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: > I noticed there is also `clear()` used in some places. Should we also mention that we don't recommend using `clear()` WRT freeing memory? > - `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 <ps@xxxxxx> > --- > 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: > + > + - `<struct>_init()` initializes a structure without allocating the > + structure itself. > + > + - `<struct>_release()` releases a structure's contents without > + freeing the structure. > + > + - `<struct>_free()` releases a structure's contents and frees the > + structure. > + > For Perl programs: > > - Most of the C guidelines above apply. > -- > 2.46.0.rc1.dirty The patch itself looks good.
Attachment:
signature.asc
Description: PGP signature
