On Mon, Mar 06, 2017 at 01:11:20PM -0500, Laine Stump wrote:
> 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@xxxxxxxxxx>
> > ---
> >
> > 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 & 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?)
Yes, that is the intention. We've already moved a bunch of stuff from
'qemu' and 'lxc' to 'virQEMU' and 'virLXC' and this just encourages
that trend.
Regards,
Daniel
--
|: http://berrange.com -o- http://www.flickr.com/photos/dberrange/ :|
|: http://libvirt.org -o- http://virt-manager.org :|
|: http://entangle-photo.org -o- http://search.cpan.org/~danberr/ :|
--
libvir-list mailing list
libvir-list@xxxxxxxxxx
https://www.redhat.com/mailman/listinfo/libvir-list
