HACKING | 80 ++++++++++++++++++++++++++++++++++++++++++++ docs/hacking.html.in | 93 ++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/hacking2.xsl | 4 +++ 3 files changed, 177 insertions(+)
This documents the preferred conventions for naming files,
structs, enums, typedefs and functions.
Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
---
Changed in v3:
- Clarify function naming wrt verb & subject
- Simplify macro naming, since in practice libvirt code doesn't follow any
rules consistently aside from having a VIR_ prefix.
HACKING | 80 ++++++++++++++++++++++++++++++++++++++++++++
docs/hacking.html.in | 93 ++++++++++++++++++++++++++++++++++++++++++++++++++++
docs/hacking2.xsl | 4 +++
3 files changed, 177 insertions(+)
diff --git a/HACKING b/HACKING
index fff003b..2c65985 100644
--- a/HACKING
+++ b/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
diff --git a/docs/hacking.html.in b/docs/hacking.html.in
index b1bb149..d904c3a 100644
--- a/docs/hacking.html.in
+++ b/docs/hacking.html.in
@@ -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>
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
On 03/06/2017 06:09 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>
> ---
>
> Changed in v3:
> - Clarify function naming wrt verb & subject
> - Simplify macro naming, since in practice libvirt code doesn't follow any
> rules consistently aside from having a VIR_ prefix.
>
> HACKING | 80 ++++++++++++++++++++++++++++++++++++++++++++
> docs/hacking.html.in | 93 ++++++++++++++++++++++++++++++++++++++++++++++++++++
> docs/hacking2.xsl | 4 +++
> 3 files changed, 177 insertions(+)
>
> diff --git a/HACKING b/HACKING
> index fff003b..2c65985 100644
> --- a/HACKING
> +++ b/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
> diff --git a/docs/hacking.html.in b/docs/hacking.html.in
> index b1bb149..d904c3a 100644
> --- a/docs/hacking.html.in
> +++ b/docs/hacking.html.in
> @@ -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,
What about the hypervisor-specific functions that are "semi-public"
(used in other files within the same directory, but not exported outside
of that directory)? I like that qemu-specific functions are prefixed
with "qemu", lxc functions with "lxc", etc. and I'm guessing you aren't
suggesting that we want those to all be "virQEMU", "virLXC", etc (or are
you?)
Regardless of that, this is useful to have as it is, and I think it's
safe to push this now and tweak it as it's discussed more, so ACK.
(unless you *want* to talk about it more :-)
> + 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>
> 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> -->
--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list
On Mon, Mar 06, 2017 at 01:11:20PM -0500, Laine Stump wrote:
> On 03/06/2017 06:09 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>
> > ---
> >
> > Changed in v3:
> > - Clarify function naming wrt verb & subject
> > - Simplify macro naming, since in practice libvirt code doesn't follow any
> > rules consistently aside from having a VIR_ prefix.
> >
> > HACKING | 80 ++++++++++++++++++++++++++++++++++++++++++++
> > docs/hacking.html.in | 93 ++++++++++++++++++++++++++++++++++++++++++++++++++++
> > docs/hacking2.xsl | 4 +++
> > 3 files changed, 177 insertions(+)
> > diff --git a/docs/hacking.html.in b/docs/hacking.html.in
> > index b1bb149..d904c3a 100644
> > --- a/docs/hacking.html.in
> > +++ b/docs/hacking.html.in
> > @@ -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,
>
> What about the hypervisor-specific functions that are "semi-public" (used in
> other files within the same directory, but not exported outside of that
> directory)? I like that qemu-specific functions are prefixed with "qemu",
> lxc functions with "lxc", etc. and I'm guessing you aren't suggesting that
> we want those to all be "virQEMU", "virLXC", etc (or are you?)
Yes, that is the intention. We've already moved a bunch of stuff from
'qemu' and 'lxc' to 'virQEMU' and 'virLXC' and this just encourages
that trend.
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
On Mon, Mar 06, 2017 at 11:09:26AM +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> > --- > > Changed in v3: > - Clarify function naming wrt verb & subject > - Simplify macro naming, since in practice libvirt code doesn't follow any > rules consistently aside from having a VIR_ prefix. > > HACKING | 80 ++++++++++++++++++++++++++++++++++++++++++++ > docs/hacking.html.in | 93 ++++++++++++++++++++++++++++++++++++++++++++++++++++ > docs/hacking2.xsl | 4 +++ > 3 files changed, 177 insertions(+) Anyone want to ack this v3 ? 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
On Mon, Mar 06, 2017 at 11:09:26 +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> > --- > > Changed in v3: > - Clarify function naming wrt verb & subject > - Simplify macro naming, since in practice libvirt code doesn't follow any > rules consistently aside from having a VIR_ prefix. > > HACKING | 80 ++++++++++++++++++++++++++++++++++++++++++++ > docs/hacking.html.in | 93 ++++++++++++++++++++++++++++++++++++++++++++++++++++ > docs/hacking2.xsl | 4 +++ > 3 files changed, 177 insertions(+) ... > diff --git a/docs/hacking.html.in b/docs/hacking.html.in > index b1bb149..d904c3a 100644 > --- a/docs/hacking.html.in > +++ b/docs/hacking.html.in > @@ -314,6 +314,99 @@ ... > + <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 s/'priv'./'priv',/ > + 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>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' s/". e.g./", e.g./ > + 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> ACK Jirka -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
On 03/06/2017 12:09 PM, 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> > --- > > Changed in v3: > - Clarify function naming wrt verb & subject > - Simplify macro naming, since in practice libvirt code doesn't follow any > rules consistently aside from having a VIR_ prefix. > > HACKING | 80 ++++++++++++++++++++++++++++++++++++++++++++ > docs/hacking.html.in | 93 ++++++++++++++++++++++++++++++++++++++++++++++++++++ > docs/hacking2.xsl | 4 +++ > 3 files changed, 177 insertions(+) > > +*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'. > + This will create some functions with ridiculously long names. qemuDomainSnapshotPrepareDiskExternalOverlayInactive() for instance. Should we lift our "80 chars per line" rule? Say to 100? Even more so since we all are working on wide screen monitors (RIP 4:3). Michal -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
On Fri, Mar 10, 2017 at 03:31:29PM +0100, Michal Privoznik wrote: > On 03/06/2017 12:09 PM, 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> > > --- > > > > Changed in v3: > > - Clarify function naming wrt verb & subject > > - Simplify macro naming, since in practice libvirt code doesn't follow any > > rules consistently aside from having a VIR_ prefix. > > > > HACKING | 80 ++++++++++++++++++++++++++++++++++++++++++++ > > docs/hacking.html.in | 93 ++++++++++++++++++++++++++++++++++++++++++++++++++++ > > docs/hacking2.xsl | 4 +++ > > 3 files changed, 177 insertions(+) > > > > > > +*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'. > > + > > This will create some functions with ridiculously long names. > qemuDomainSnapshotPrepareDiskExternalOverlayInactive() for instance. > Should we lift our "80 chars per line" rule? Say to 100? Even more so > since we all are working on wide screen monitors (RIP 4:3). NB, these are naming guidelines not rules, so I'd say it is fine to adapt to a better short name, if the guidelines would result in such a ridiculously long name. 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
On Fri, 2017-03-10 at 15:31 +0100, Michal Privoznik wrote: > This will create some functions with ridiculously long names. > qemuDomainSnapshotPrepareDiskExternalOverlayInactive() for instance. Personally, I'd rather have long but descriptive names rather than ambiguous ones. > Should we lift our "80 chars per line" rule? Say to 100? Even more so > since we all are working on wide screen monitors (RIP 4:3). We're no longer enforcing that limit anyway. -- Andrea Bolognani / Red Hat / Virtualization -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
© 2016 - 2024 Red Hat, Inc.