From nobody Sun Apr 28 22:51:03 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of redhat.com designates 209.132.183.39 as permitted sender) client-ip=209.132.183.39; envelope-from=libvir-list-bounces@redhat.com; helo=mx6-phx2.redhat.com; Authentication-Results: mx.zoho.com; spf=pass (zoho.com: domain of redhat.com designates 209.132.183.39 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; Return-Path: Received: from mx6-phx2.redhat.com (mx6-phx2.redhat.com [209.132.183.39]) by mx.zohomail.com with SMTPS id 1488534730436937.9172437725439; Fri, 3 Mar 2017 01:52:10 -0800 (PST) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by mx6-phx2.redhat.com (8.14.4/8.14.4) with ESMTP id v239mTFN032490; Fri, 3 Mar 2017 04:48:29 -0500 Received: from int-mx11.intmail.prod.int.phx2.redhat.com (int-mx11.intmail.prod.int.phx2.redhat.com [10.5.11.24]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id v239mS1H019878 for ; Fri, 3 Mar 2017 04:48:28 -0500 Received: from t460.redhat.com (ovpn-117-177.ams2.redhat.com [10.36.117.177]) by int-mx11.intmail.prod.int.phx2.redhat.com (8.14.4/8.14.4) with ESMTP id v239mQHe027615; Fri, 3 Mar 2017 04:48:27 -0500 From: "Daniel P. Berrange" To: libvir-list@redhat.com Date: Fri, 3 Mar 2017 09:48:23 +0000 Message-Id: <20170303094823.10006-1-berrange@redhat.com> X-Scanned-By: MIMEDefang 2.68 on 10.5.11.24 X-loop: libvir-list@redhat.com Subject: [libvirt] [PATCH] Document preferred naming conventions X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-ZohoMail: RSF_0 Z_629925259 SPT_0 Content-Type: text/plain; charset="utf-8" This documents the preferred conventions for naming files, structs, enums, typedefs and functions. Signed-off-by: Daniel P. Berrange --- 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 wit= h open source projects . =20 =20 +Naming conventions +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +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 i= t is +desirable to apply these conventions, keeping a consistent style with exis= ting +code in that particular file is generally more important. The overall guid= ing +rule is that every file, enum, struct, function, and typedef name must hav= e a +'vir' or 'VIR' prefix. All local scope variable names are exempt, and glob= al +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 obj= ect +'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 sh= ould +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/ directorie= s. +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 follo= wing +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 na= me +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. For example, gi= ven +an object 'virHashTable', all functions should have a name 'virHashTableXX= XX' +e.g. 'virHashTableLookup'. If there is no object associated with the funct= ion, +then its name prefix should match the filename. For example, given a filen= ame +of 'virfile.h', all functions should have a name 'virFileXXXX' e.g. +'virFileTouch'. + + + + Code indentation =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D 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.

=20 +

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 follo= wed + when creating any entirely new files in libvirt. When working on exi= sting + files, while it is desirable to apply these conventions, keeping a + consistent style with existing code in that particular file is gener= ally + more important. The overall guiding rule is that every file, enum, s= truct, + function, and typedef name must have a 'vir' or 'VIR' prefix. All l= ocal + scope variable names are exempt, and global variables are exempt, un= less + 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. + 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'. +

+
+
=20

Code indentation

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:value-of select=3D"$newline"/> =20 +** + + + =20 =20 --=20 2.9.3 -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list