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

[Junio C Hamano <gitster@pobox.com>]

Patrick Steinhardt <ps@pks.im> writes:

> + - Functions that operate on a specific structure and which are used by
> +   other subsystems shall be named after the structure.

I am not sure if this is a good guideline.  In the case of strbuf_,
you could say it is named after the structure, but I would actually
think that both structure and the functions are named after the
subsystem/API (i.e. we have "strbuf" that other subsystems can use).

> + The function
> +   name should start with the name of the structure followed by a verb.
> +   E.g.
> +
> +	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, ...);
> +
> +	void reset_strbuf(struct strbuf *buf);

Do we want to rename start_command(), finish_command(),
run_command() and pipe_command()?  child_process_start() sounds
somewhat ungrammatical.

By the way, some functions that have strbuf_ in their names do not
have anything to do with managing strings using the strbuf
structure, but they do things that are *not* about strings, but
happen to use strbuf as a way to either feed input to them or carry
output out of them.  They should be renamed away to lose "strbuf_"
in their names (e.g. strbuf_realpath() is about pathnames; it is
immaterial that the function happens to use strbuf to hold its
output but takes input from "const char *").