[libvirt] [PATCH v3] Document preferred naming conventions

[Daniel P. Berrange]

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 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 @@
> >           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/ :|