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

On 03/06/2017 06:09 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; > --- > > 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 @@ > Richard Jones' guide to working with open source projects</a>. > </p> > + <h2><a name="naming">Naming conventions</a></h2> > + > + <p> > + 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 principal is that every file, enum, > + struct, function, macro 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. > + </p> > + > + <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>Enum type &amp; field names</dt> > + <dd> > + <p> > + All enums should have a 'vir' prefix in their typedef name, > + and each following word should have its first letter in > + uppercase. The enum name should match the typedef name with > + a leading underscore. The enum member names should be in all > + uppercase, and use an underscore to separate each word. The > + enum member name prefix should match the enum typedef name. > + </p> > + <pre> > + typedef enum _virSocketType virSocketType; > + enum _virSocketType { > + VIR_SOCKET_TYPE_IPV4, > + VIR_SOCKET_TYPE_IPV6, > + };</pre> > + </dd> > + <dt>Struct type names</dt> > + <dd> > + <p> > + All structs should have a 'vir' prefix in their typedef name, > + and each following word should have its first letter in > + uppercase. The struct name should be the same as the typedef > + name with a leading underscore. A second typedef should be > + given for a pointer to the struct with a 'Ptr' suffix. > + </p> > + <pre> > + typedef struct _virHashTable virHashTable; > + typedef virHashTable *virHashTablePtr; > + struct _virHashTable { > + ... > + };</pre> > + </dd> > + <dt>Function names</dt> > + <dd> > + <p> > + All functions should have a 'vir' prefix in their name, What about the hypervisor-specific functions that are "semi-public" (used in other files within the same directory, but not exported outside of that directory)? I like that qemu-specific functions are prefixed with "qemu", lxc functions with "lxc", etc. and I'm guessing you aren't suggesting that we want those to all be "virQEMU", "virLXC", etc (or are you?)