[libvirt] [PATCH] Document preferred naming conventions

Daniel P. Berrange posted 1 patch 7 years ago
Patches applied successfully (tree, apply log)
git fetch https://github.com/patchew-project/libvirt tags/patchew/20170303094823.10006-1-berrange@redhat.com
There is a newer version of this series
HACKING              | 71 ++++++++++++++++++++++++++++++++++++++++++++
docs/hacking.html.in | 83 ++++++++++++++++++++++++++++++++++++++++++++++++++++
docs/hacking2.xsl    |  4 +++
3 files changed, 158 insertions(+)
[libvirt] [PATCH] Document preferred naming conventions
Posted by Daniel P. Berrange 7 years ago
This documents the preferred conventions for naming files,
structs, enums, typedefs and functions.

Signed-off-by: Daniel P. Berrange <berrange@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 {
+       ...
+    };
+
+
+*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'.
+
+
+
+
 Code indentation
 ================
 Libvirt's C source code generally adheres to some basic code-formatting
diff --git a/docs/hacking.html.in b/docs/hacking.html.in
index b1bb149..028536d 100644
--- a/docs/hacking.html.in
+++ b/docs/hacking.html.in
@@ -314,6 +314,89 @@
         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 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.
+    </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,
+          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'.
+          </p>
+      </dd>
+    </dl>
 
     <h2><a name="indent">Code indentation</a></h2>
     <p>
diff --git a/docs/hacking2.xsl b/docs/hacking2.xsl
index 3595b7e..7e5ac82 100644
--- a/docs/hacking2.xsl
+++ b/docs/hacking2.xsl
@@ -114,6 +114,10 @@ from docs/hacking.html.in!
 <xsl:template match="html:li/html:ul/html:li">-- <xsl:apply-templates/><xsl:value-of select="$newline"/><xsl:value-of select="$newline"/>
 </xsl:template>
 
+<xsl:template match="html:dl/html:dt">*<xsl:apply-templates/>*<xsl:value-of select="$newline"/><xsl:value-of select="$newline"/>
+</xsl:template>
+<xsl:template match="html:dl/html:dd"><xsl:apply-templates/><xsl:value-of select="$newline"/><xsl:value-of select="$newline"/>
+</xsl:template>
 
 
 <!-- add newline before nested <ul> -->
-- 
2.9.3

--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list
Re: [libvirt] [PATCH] Document preferred naming conventions
Posted by Peter Krempa 7 years ago
On Fri, Mar 03, 2017 at 09:48:23 +0000, Daniel Berrange wrote:
> This documents the preferred conventions for naming files,
> structs, enums, typedefs and functions.
> 
> Signed-off-by: Daniel P. Berrange <berrange@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

s/USe/Use/

> +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 {
> +       ...
> +    };
> +
> +
> +*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'.
> +

I'd also add that macro names should be all caps, while macro argument
names should not.

Other than that ACK. Finally we can point offenders to this doc.

Peter
--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list
Re: [libvirt] [PATCH] Document preferred naming conventions
Posted by Martin Kletzander 7 years ago
On Fri, Mar 03, 2017 at 09:48:23AM +0000, Daniel P. Berrange wrote:
>This documents the preferred conventions for naming files,
>structs, enums, typedefs and functions.
>
>Signed-off-by: Daniel P. Berrange <berrange@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.
>+

Why not?  I think src/conf/ should (and does) follow, so does
src/access/, I would even go as far as saying every src/ directory that
is not a hypervisor driver.  But I, personally, would not be offended by
all of them being changed.

Rest looks fine to me.

Martin
--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list
Re: [libvirt] [PATCH] Document preferred naming conventions
Posted by Daniel P. Berrange 7 years ago
On Fri, Mar 03, 2017 at 03:10:11PM +0100, Martin Kletzander wrote:
> On Fri, Mar 03, 2017 at 09:48:23AM +0000, Daniel P. Berrange wrote:
> > This documents the preferred conventions for naming files,
> > structs, enums, typedefs and functions.
> > 
> > Signed-off-by: Daniel P. Berrange <berrange@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.
> > +
> 
> Why not?  I think src/conf/ should (and does) follow, so does
> src/access/, I would even go as far as saying every src/ directory that
> is not a hypervisor driver.  But I, personally, would not be offended by
> all of them being changed.

I didn't mean to imply that the other directories shouldn't change - I was
just documenting effective current usage. If we want to rename all existing
files to have a vir prefix, I'd certainly be open to considering such a
change. It makes backports a little more painful, but generally git can
detect the rename correctly when chery-picking. If we did such a change,
then obviously we could change this text to match at that point.


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@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list
Re: [libvirt] [PATCH] Document preferred naming conventions
Posted by Michal Privoznik 7 years ago
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@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.

so for instance src/util/virhostdev.c should be renamed to
virdomainhostdev.c?

> +
> +
> +
> +*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 {
> +       ...
> +    };
> +
> +
> +*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.

> +
> +
> +
> +

Michal

--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list
Re: [libvirt] [PATCH] Document preferred naming conventions
Posted by Daniel P. Berrange 7 years ago
On Fri, Mar 03, 2017 at 03:19:46PM +0100, Michal Privoznik wrote:
> 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@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.
> 
> so for instance src/util/virhostdev.c should be renamed to
> virdomainhostdev.c?

The APIs in that file are virHostdevXXXX, and the primary
object name is virHostdevManager for most of them, though
they do also have a virDomainHostdev. On balance virhostdev.c
is right I think.

> > +*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.

I guess I was trying to imply that by saying virFileXXX, but yeah, sometimes
"Module" & "Object" are different. So yeah, lets explicitly say that "Verb"
always comes last

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@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list
Re: [libvirt] [PATCH] Document preferred naming conventions
Posted by Bjoern Walk 7 years ago
Daniel P. Berrange <berrange@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@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.

>+
>+*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'.
>+
>+
>+
>+
> Code indentation
> ================
> Libvirt's C source code generally adheres to some basic code-formatting
>diff --git a/docs/hacking.html.in b/docs/hacking.html.in
>index b1bb149..028536d 100644
>--- a/docs/hacking.html.in
>+++ b/docs/hacking.html.in
>@@ -314,6 +314,89 @@
>         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 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.
>+    </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,
>+          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'.
>+          </p>
>+      </dd>
>+    </dl>
>
>     <h2><a name="indent">Code indentation</a></h2>
>     <p>
>diff --git a/docs/hacking2.xsl b/docs/hacking2.xsl
>index 3595b7e..7e5ac82 100644
>--- a/docs/hacking2.xsl
>+++ b/docs/hacking2.xsl
>@@ -114,6 +114,10 @@ from docs/hacking.html.in!
> <xsl:template match="html:li/html:ul/html:li">-- <xsl:apply-templates/><xsl:value-of select="$newline"/><xsl:value-of select="$newline"/>
> </xsl:template>
>
>+<xsl:template match="html:dl/html:dt">*<xsl:apply-templates/>*<xsl:value-of select="$newline"/><xsl:value-of select="$newline"/>
>+</xsl:template>
>+<xsl:template match="html:dl/html:dd"><xsl:apply-templates/><xsl:value-of select="$newline"/><xsl:value-of select="$newline"/>
>+</xsl:template>
>
>
> <!-- add newline before nested <ul> -->
>-- 
>2.9.3
>
>--
>libvir-list mailing list
>libvir-list@redhat.com
>https://www.redhat.com/mailman/listinfo/libvir-list
>

-- 
IBM Systems
Linux on z Systems & Virtualization Development
------------------------------------------------------------------------
IBM Deutschland
Schönaicher Str. 220
71032 Böblingen
Phone: +49 7031 16 1819
E-Mail: bwalk@de.ibm.com
------------------------------------------------------------------------
IBM Deutschland Research & Development GmbH
Vorsitzende des Aufsichtsrats: Martina Koederitz
Geschäftsführung: Dirk Wittkopp
Sitz der Gesellschaft: Böblingen
Registergericht: Amtsgericht Stuttgart, HRB 243294 
--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list
Re: [libvirt] [PATCH] Document preferred naming conventions
Posted by Peter Krempa 7 years ago
On Mon, Mar 06, 2017 at 10:21:28 +0100, Bjoern Walk wrote:
> Daniel P. Berrange <berrange@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@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.

The two part declaration is necessary if you want to hide the
implementation of the struct in the .c file so that other places can't
access it directly, thus we'd either have to allow both, or the two part
can be the only one used. See src/conf/numa_conf.(c|h) for example of
the above.
--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list
Re: [libvirt] [PATCH] Document preferred naming conventions
Posted by Bjoern Walk 7 years ago
Peter Krempa <pkrempa@redhat.com> [2017-03-06, 10:40AM +0100]:
>On Mon, Mar 06, 2017 at 10:21:28 +0100, Bjoern Walk wrote:
>> 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.
>
>The two part declaration is necessary if you want to hide the
>implementation of the struct in the .c file so that other places can't
>access it directly, thus we'd either have to allow both, or the two part
>can be the only one used. See src/conf/numa_conf.(c|h) for example of
>the above.

Fair enough, didn't think of this. Still, maybe the fact that with the
combined declaration one can jump directly to a type outweighs the
benefits of this strict encapsulation? It just is often very annoying to
have to jump through an additional hoop and it may break some tools like
code completion. Also, a misuse of the type in a different place can
easily prevented by review.

But well, I just wanted to chip in with a discussion, at least I know
see that there is a valid use for this pattern.

>--
>libvir-list mailing list
>libvir-list@redhat.com
>https://www.redhat.com/mailman/listinfo/libvir-list


-- 
IBM Systems
Linux on z Systems & Virtualization Development
------------------------------------------------------------------------
IBM Deutschland
Schönaicher Str. 220
71032 Böblingen
Phone: +49 7031 16 1819
E-Mail: bwalk@de.ibm.com
------------------------------------------------------------------------
IBM Deutschland Research & Development GmbH
Vorsitzende des Aufsichtsrats: Martina Koederitz
Geschäftsführung: Dirk Wittkopp
Sitz der Gesellschaft: Böblingen
Registergericht: Amtsgericht Stuttgart, HRB 243294 
--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list
Re: [libvirt] [PATCH] Document preferred naming conventions
Posted by Daniel P. Berrange 7 years ago
On Mon, Mar 06, 2017 at 10:21:28AM +0100, Bjoern Walk wrote:
> Daniel P. Berrange <berrange@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@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/ :|

--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list
Re: [libvirt] [PATCH] Document preferred naming conventions
Posted by Laine Stump 7 years ago
On 03/06/2017 05:04 AM, Daniel P. Berrange wrote:
> On Mon, Mar 06, 2017 at 10:21:28AM +0100, Bjoern Walk wrote:
>> Daniel P. Berrange <berrange@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@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.

There are others too. I've always disliked the separate typedefs and 
extra _virBlah struct name, so quite awhile back I posted some patches 
that used the more compact style in new struct definitions as a way of 
suggesting that we use that instead, and they passed review. So I did 
several more that way, and those passed as well (although I do remember 
one dissenting opinion for one patch).

But if we're going to formalize struct definitions in a coding standards 
document, then I'm willing to throw in the towel - to avoid leading 
unsuspecting copy-pasters in the wrong direction, I just sent a patch 
that changes all "compact format" struct definitions to the more verbose 
format in the document.



--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list