[libvirt] [PATCH] Document preferred naming conventions

[Daniel P. Berrange]

On Mon, Mar 06, 2017 at 10:21:28AM +0100, Bjoern Walk wrote:
> Daniel P. Berrange <berrange at redhat.com> [2017-03-03, 10:50AM +0100]:
> > This documents the preferred conventions for naming files,
> > structs, enums, typedefs and functions.
> > 
> > Signed-off-by: Daniel P. Berrange <berrange at redhat.com>
> > ---
> > 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-projects/>.
> > 
> > 
> > +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.
> > +
> > +
> > +
> > +*Enum type & field names*
> > +
> > +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.
> > +
> > +    typedef enum _virSocketType virSocketType;
> > +    enum _virSocketType {
> > +        VIR_SOCKET_TYPE_IPV4,
> > +        VIR_SOCKET_TYPE_IPV6,
> > +    };
> > +
> > +
> > +*Struct type names*
> > +
> > +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.
> > +
> > +    typedef struct _virHashTable virHashTable;
> > +    typedef virHashTable *virHashTablePtr;
> > +    struct _virHashTable {
> > +       ...
> > +    };
> > +
> 
> I personally would prefer this style:
> 
>    typedef struct _virHashTable {
>       ...
>    } virHashTable, *virHashTablePtr;
> This is done for example in src/conf/device_conf.h. Subjectively, it is
> much easier to read, but objectively, it is more concise and enhances
> discoverability. For example, in src/conf/domain_conf.h the typedef are
> at the beginning of the file separated from the definition of the
> struct. If I want to look up a virDomainDiskDefPtr it requires two
> jumps.

We should change device_conf.h really - it is different from pretty much
everywhere else in the libvirt codebase.

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