Re: [libvirt] [PATCH v3] Document preferred naming conventions

This documents the preferred conventions for naming files, structs, enums, typedefs and functions. Signed-off-by: Daniel P. Berrange <berrange(a)redhat.com&gt; --- 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

+ 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'

+ 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>