HACKING | 81 ++++++++++++++++++++++++++++++++++++++++++++ docs/hacking.html.in | 94 ++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/hacking2.xsl | 4 +++ 3 files changed, 179 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 v2:
- Fix typo
- Add macro docs
- Clarify that $VERB is always last in function/macro names
HACKING | 81 ++++++++++++++++++++++++++++++++++++++++++++
docs/hacking.html.in | 94 ++++++++++++++++++++++++++++++++++++++++++++++++++++
docs/hacking2.xsl | 4 +++
3 files changed, 179 insertions(+)
diff --git a/HACKING b/HACKING
index fff003b..5077304 100644
--- a/HACKING
+++ b/HACKING
@@ -239,6 +239,87 @@ 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 {
+ ...
+ };
+
+
+*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. When naming
+functions the verb should always be the last part of the name. For example,
+given an object 'virHashTable', all functions should have a name
+'virHashTable$VERB' 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
+'virFile$VERB' e.g. 'virFileTouch'.
+
+
+
+*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. As with functions, the verb should always be the last part of
+the name. For example "VIR_FILE_CLOSE".
+
+
+
+
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..1001f49 100644
--- a/docs/hacking.html.in
+++ b/docs/hacking.html.in
@@ -314,6 +314,100 @@
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.
+ When naming functions the verb should always be the last
+ part of the name. For example, given an object 'virHashTable',
+ all functions should have a name 'virHashTable$VERB'
+ 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 'virFile$VERB' e.g. 'virFileTouch'.
+ </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. As with functions,
+ the verb should always be the last part of the name. For example
+ "VIR_FILE_CLOSE".
+ </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 Fri, Mar 03, 2017 at 17:47:23 +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 v2:
>
> - Fix typo
> - Add macro docs
> - Clarify that $VERB is always last in function/macro names
Hmm, so what do we do if there is an object, an action, and a subject?
Typically accessors which are designed to return some specific part of
the object. For example,
virQEMUCapsGetDefaultMachine
\ / | \ /
object | subject
|
`- action (verb)
Are we supposed to name such function as virQEMUCapsDefaultMachineGet?
While it is certainly possible, it just doesn't read well.
Jirka
P.S. No nit-picking intended, I'm just trying to avoid future flames on
this matter.
--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list
On Fri, Mar 03, 2017 at 07:57:24PM +0100, Jiri Denemark wrote: > On Fri, Mar 03, 2017 at 17:47:23 +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 v2: > > > > - Fix typo > > - Add macro docs > > - Clarify that $VERB is always last in function/macro names > > Hmm, so what do we do if there is an object, an action, and a subject? Good question :-) > Typically accessors which are designed to return some specific part of > the object. For example, > > virQEMUCapsGetDefaultMachine > \ / | \ / > object | subject > | > `- action (verb) > > Are we supposed to name such function as virQEMUCapsDefaultMachineGet? > While it is certainly possible, it just doesn't read well. Yeah that's craziness in that example at least. Do you recall any examples where we have object,subject,action, or are we always doing object,action,subject ? We could specify object,action,subject, or we could just say either ordering of action & subject is valid. 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, Mar 03, 2017 at 19:16:58 +0000, Daniel P. Berrange wrote:
> On Fri, Mar 03, 2017 at 07:57:24PM +0100, Jiri Denemark wrote:
> > On Fri, Mar 03, 2017 at 17:47:23 +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 v2:
> > >
> > > - Fix typo
> > > - Add macro docs
> > > - Clarify that $VERB is always last in function/macro names
> >
> > Hmm, so what do we do if there is an object, an action, and a subject?
>
> Good question :-)
>
> > Typically accessors which are designed to return some specific part of
> > the object. For example,
> >
> > virQEMUCapsGetDefaultMachine
> > \ / | \ /
> > object | subject
> > |
> > `- action (verb)
> >
> > Are we supposed to name such function as virQEMUCapsDefaultMachineGet?
> > While it is certainly possible, it just doesn't read well.
>
> Yeah that's craziness in that example at least. Do you recall any examples
> where we have object,subject,action, or are we always doing
> object,action,subject ?
I went through qemu_capabilities.c and found a few examples which do not
follow object,action,subject:
virQEMUCapsCPUFilterFeatures
- this is strange and should be changed
virQEMUCapsQMPSchemaObjectGetType
virQEMUCapsQMPSchemaTraverse
virQEMUCapsQMPSchemaGetByPath
- these are quite innovative, they look as if
virQEMUCapsQMPSchema{,Object} were objects on which the functions
operate, but there are no objects with such names defined; still I
think the names don't need to be changed
> We could specify object,action,subject, or we could just say either
> ordering of action & subject is valid.
Maybe we could specify object,action,subject, while still allowing other
variants if they read better (although I can't think of any example).
Jirka
--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list
On 03/03/2017 02:16 PM, Daniel P. Berrange wrote: > On Fri, Mar 03, 2017 at 07:57:24PM +0100, Jiri Denemark wrote: >> >> Hmm, so what do we do if there is an object, an action, and a subject? > Good question :-) > >> Typically accessors which are designed to return some specific part of >> the object. For example, >> >> virQEMUCapsGetDefaultMachine >> \ / | \ / >> object | subject >> | >> `- action (verb) >> >> Are we supposed to name such function as virQEMUCapsDefaultMachineGet? >> While it is certainly possible, it just doesn't read well. > Yeah that's craziness in that example at least. Do you recall any examples > where we have object,subject,action, or are we always doing > object,action,subject ? Just to throw more wrenches in the works: There are a *lot* of auto-generated function names like virEnumNameTypeFromString() and virEnumNameTypeToString(). If we ever decided we wanted full consistency (as if that is even *possible* :-P), would we make those virEnumNameGetString() and virStringGetEnumName() ? (but of course then some pedant would expect virStringGetEnumName() to be in virstring.[ch] :-P) This discussion is apropos for me, as I just made a new function that turns an SRIOV PFnetdevname + VF# into a VFnetdevname. I had just mindlessly called it virNetDevGetVFFromPF() (existing functions spell out PhysicalFunction and VirtualFunction but I think that's too long even when only one is involved), but after reading through this and actually *thinking* about it, I renamed it to virNetDevPFGetVF(). (Considering the alternatives, I think "virNetDevPhysicalFunctionVirtualFunctionGet() would be fairly horrible... Or what about virNetDevPFVFGet() ?) > > We could specify object,action,subject, or we could just say either > ordering of action & subject is valid. There have been times in the past when any way it was ordered led to something that seemed nonsensical. I think it would help people like me who worry over names to have at least a suggestion so that the tie could be broken in cases where we couldn't make up our mind (i.e. a place to point the finger when a reviewer questions our choice of name :-) -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list
© 2016 - 2024 Red Hat, Inc.