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: > > - `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. We have _clear() in some subsystem/API. Are we sure the listed two are sufficient and _clear() can be replaced with one of them (perhaps _release())? > 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.
