NuKVM/libvirt
3
0
Fork 0
mirror of https://github.com/libvirt/libvirt.git synced 2025-02-25 18:55:26 -06:00
Code Issues Packages Projects Releases Wiki Activity

Document preferred naming conventions

Browse Source 
This documents the preferred conventions for naming files,
structs, enums, typedefs and functions.

Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
This commit is contained in:
Daniel P. Berrange 2017-03-03 09:46:16 +00:00
parent 887ffbce43
commit 33feb66608
3 changed files with 177 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

80
HACKING
View File

@ -239,6 +239,86 @@ 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/>. <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
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.
*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, otherwise it should
match the filename. Following this comes the verb / action name, and finally
an optional subject name. For example, given an object 'virHashTable', all
functions should have a name 'virHashTable$VERB' or
'virHashTable$VERB$SUBJECT", e.g. 'virHashTableLookup' or
'virHashTableGetValue'.
*Macro names*
All macros should have a "VIR" prefix in their name, followed by one or more
uppercase words separated by underscores. The macro argument names should be
in lowercase. Aside from having a "VIR" prefix there are no common practices
for the rest of the macro name.
Code indentation Code indentation
================ ================
Libvirt's C source code generally adheres to some basic code-formatting Libvirt's C source code generally adheres to some basic code-formatting

93
docs/hacking.html.in
View File

@ -314,6 +314,99 @@
Richard Jones' guide to working with open source projects</a>. Richard Jones' guide to working with open source projects</a>.
</p> </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 &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,
otherwise it should match the filename. Following this
comes the verb / action name, and finally an optional
subject name. For example, given an object 'virHashTable',
all functions should have a name 'virHashTable$VERB' or
'virHashTable$VERB$SUBJECT", e.g. 'virHashTableLookup'
or 'virHashTableGetValue'.
</p>
</dd>
<dt>Macro names</dt>
<dd>
<p>
All macros should have a "VIR" prefix in their name, followed
by one or more uppercase words separated by underscores. The
macro argument names should be in lowercase. Aside from having
a "VIR" prefix there are no common practices for the rest of
the macro name.
</p>
</dd>
</dl>
<h2><a name="indent">Code indentation</a></h2> <h2><a name="indent">Code indentation</a></h2>
<p> <p>

4
docs/hacking2.xsl
View File

@ -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 match="html:li/html:ul/html:li">-- <xsl:apply-templates/><xsl:value-of select="$newline"/><xsl:value-of select="$newline"/>
</xsl:template> </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> --> <!-- add newline before nested <ul> -->