Daniel P. Berrange <berrange@xxxxxxxxxx> [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@xxxxxxxxxx> --- 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@xxxxxxxxxx
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@xxxxxxxxxx ------------------------------------------------------------------------ IBM Deutschland Research & Development GmbH Vorsitzende des Aufsichtsrats: Martina Koederitz Geschäftsführung: Dirk Wittkopp Sitz der Gesellschaft: BöblingenRegistergericht: Amtsgericht Stuttgart, HRB 243294
Attachment:
signature.asc
Description: PGP signature
-- libvir-list mailing list libvir-list@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/libvir-list
