Re: [PATCH 2/3] Documentation: document naming schema for struct-related functions

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Patrick Steinhardt <ps@xxxxxx> writes:

> We nowadays have a proper mishmash of struct-related functions that are
> called `<verb>_<struct>` (e.g. `clear_prio_queue()`) versus functions
> that are called `<struct>_<verb>` (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 <ps@xxxxxx>
> ---
>  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.
> +

Nit: It would be nice to add `<struct>_<verb>` here, since we do something
similar in the next patch.

> +	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, ...);
> +

I first thought this was a typo and should've been `add_strbuf` instead,
but I'm sure your intention was to show _other forms_ instead of
`<struct>_<verb>` here.

Maybe we could do s/is preferred over/is preferred over other forms,
like/. I dunno. It is probably fine as is :)

> +	void reset_strbuf(struct strbuf *buf);
> +
>  For Perl programs:
>
>   - Most of the C guidelines above apply.
> --
> 2.46.0.rc1.dirty

Attachment: signature.asc
Description: PGP signature


[Index of Archives]     [Linux Kernel Development]     [Gcc Help]     [IETF Annouce]     [DCCP]     [Netdev]     [Networking]     [Security]     [V4L]     [Bugtraq]     [Yosemite]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Linux SCSI]     [Fedora Users]

  Powered by Linux