mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-12-22 13:45:38 +00:00
Document preferred naming conventions
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
parent
887ffbce43
commit
33feb66608
80
HACKING
80
HACKING
@ -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/>.
|
||||
|
||||
|
||||
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
|
||||
================
|
||||
Libvirt's C source code generally adheres to some basic code-formatting
|
||||
|
||||
@ -314,6 +314,99 @@
|
||||
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 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 & 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>
|
||||
<p>
|
||||
|
||||
@ -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> -->
|
||||
|
||||
Loading…
Reference in New Issue
Block a user