[libvirt] [PATCH v3] Document preferred naming conventions

[Jiri Denemark]

On Mon, Mar 06, 2017 at 11:09:26 +0000, Daniel P. Berrange wrote:
> This documents the preferred conventions for naming files,
> structs, enums, typedefs and functions.
> 
> Signed-off-by: Daniel P. Berrange <berrange at redhat.com>
> ---
> 
> Changed in v3:
>  - Clarify function naming wrt verb & subject
>  - Simplify macro naming, since in practice libvirt code doesn't follow any
>    rules consistently aside from having a VIR_ prefix.
> 
>  HACKING              | 80 ++++++++++++++++++++++++++++++++++++++++++++
>  docs/hacking.html.in | 93 ++++++++++++++++++++++++++++++++++++++++++++++++++++
>  docs/hacking2.xsl    |  4 +++
>  3 files changed, 177 insertions(+)
...
> diff --git a/docs/hacking.html.in b/docs/hacking.html.in
> index b1bb149..d904c3a 100644
> --- a/docs/hacking.html.in
> +++ b/docs/hacking.html.in
> @@ -314,6 +314,99 @@
...
> +    <dl>
> +      <dt>File names</dt>
> +      <dd>
> +        <p>
> +          File naming varies depending on the subdirectory. The preferred
> +          style is to have a 'vir' prefix, followed by a name which matches
> +          the name of the functions / objects inside the file. For example,
> +          a file containing an object  'virHashtable' is stored in files
> +          'virhashtable.c' and 'virhashtable.h'. Sometimes, methods which
> +          would otherwise be declared 'static' need to be exported for use
> +          by a test suite. For this purpose a second header file should be
> +          added with a suffix of 'priv'. e.g. 'virhashtablepriv.h'. Use of

s/'priv'./'priv',/

> +          underscores in file names is discouraged when using the 'vir'
> +          prefix style. The 'vir' prefix naming applies to src/util,
> +          src/rpc and tests/ directories. Most other directories do not
> +          follow this convention.
> +        </p>
> +      </dd>
...
> +      <dt>Function names</dt>
> +      <dd>
> +        <p>
> +          All functions should have a 'vir' prefix in their name,
> +          followed by one or more words with first letter of each
> +          word capitalized. Underscores should not be used in function
> +          names. If the function is operating on an object, then the
> +          function name prefix should match the object typedef name,
> +          otherwise it should match the filename. Following this
> +          comes the verb / action name, and finally an optional
> +          subject name. For example, given an object 'virHashTable',
> +          all functions should have a name 'virHashTable$VERB' or
> +          'virHashTable$VERB$SUBJECT". e.g. 'virHashTableLookup'

s/". e.g./", e.g./

> +          or 'virHashTableGetValue'.
> +        </p>
> +      </dd>
> +      <dt>Macro names</dt>
> +      <dd>
> +        <p>
> +          All macros should have a "VIR" prefix in their name, followed
> +          by one or more uppercase words separated by underscores. The
> +          macro argument names should be in lowercase. Aside from having
> +          a "VIR" prefix there are no common practices for the rest of
> +          the macro name.
> +        </p>
> +      </dd>
> +    </dl>

ACK

Jirka