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

On 03/03/2017 10:48 AM, Daniel P. Berrange wrote: > This documents the preferred conventions for naming files, > structs, enums, typedefs and functions. > > Signed-off-by: Daniel P. Berrange <berrange(a)redhat.com&gt; > --- > HACKING | 71 ++++++++++++++++++++++++++++++++++++++++++++ > docs/hacking.html.in | 83 ++++++++++++++++++++++++++++++++++++++++++++++++++++ > docs/hacking2.xsl | 4 +++ > 3 files changed, 158 insertions(+) > > diff --git a/HACKING b/HACKING > index fff003b..16be5cf 100644 > --- a/HACKING > +++ b/HACKING > @@ -239,6 +239,77 @@ on the subject, on Richard Jones' guide to working with open source projects > <http://people.redhat.com/rjones/how-to-supply-code-to-open-source-project...;. > > > +Naming conventions > +================== > +When reading libvirt code, a number of different naming conventions will be > +evident due to various changes in thinking over the course of the project's > +lifetime. The conventions documented below should be followed when creating > +any entirely new files in libvirt. When working on existing files, while it is > +desirable to apply these conventions, keeping a consistent style with existing > +code in that particular file is generally more important. The overall guiding > +rule is that every file, enum, struct, function, and typedef name must have a > +'vir' or 'VIR' prefix. All local scope variable names are exempt, and global > +variables are exempt, unless exported in a header file. > + > +*File names* > + > +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. so for instance src/util/virhostdev.c should be renamed to virdomainhostdev.c?

> +*Function names* > + > +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. For example, given > +an object 'virHashTable', all functions should have a name 'virHashTableXXXX' > +e.g. 'virHashTableLookup'. If there is no object associated with the function, > +then its name prefix should match the filename. For example, given a filename > +of 'virfile.h', all functions should have a name 'virFileXXXX' e.g. > +'virFileTouch'. While we are at this, should we standardize the construction of the name too? I mean, sometimes it's virModuleVerbObject while other times it's virModuleObjectVerb.