[libvirt] [PATCH] Document preferred naming conventions
Bjoern Walk
bwalk at linux.vnet.ibm.com
Mon Mar 6 09:21:28 UTC 2017
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.
>+
>+*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 & 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 at 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 at 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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 896 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20170306/42817f8d/attachment-0001.sig>
More information about the libvir-list
mailing list