From nobody Sun May 5 14:10:45 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of redhat.com designates 209.132.183.37 as permitted sender) client-ip=209.132.183.37; envelope-from=libvir-list-bounces@redhat.com; helo=mx5-phx2.redhat.com; Authentication-Results: mx.zoho.com; spf=pass (zoho.com: domain of redhat.com designates 209.132.183.37 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; Return-Path: Received: from mx5-phx2.redhat.com (mx5-phx2.redhat.com [209.132.183.37]) by mx.zohomail.com with SMTPS id 1488798778401483.5079766051151; Mon, 6 Mar 2017 03:12:58 -0800 (PST) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by mx5-phx2.redhat.com (8.14.4/8.14.4) with ESMTP id v26B9XPK037443; Mon, 6 Mar 2017 06:09:33 -0500 Received: from smtp.corp.redhat.com (int-mx16.intmail.prod.int.phx2.redhat.com [10.5.11.28]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id v26B9W88006681 for ; Mon, 6 Mar 2017 06:09:32 -0500 Received: by smtp.corp.redhat.com (Postfix) id 32FAF2D5C0; Mon, 6 Mar 2017 11:09:32 +0000 (UTC) Received: from t460.redhat.com (ovpn-117-205.ams2.redhat.com [10.36.117.205]) by smtp.corp.redhat.com (Postfix) with ESMTP id EF8692D653; Mon, 6 Mar 2017 11:09:30 +0000 (UTC) From: "Daniel P. Berrange" To: libvir-list@redhat.com Date: Mon, 6 Mar 2017 11:09:26 +0000 Message-Id: <20170306110926.4432-1-berrange@redhat.com> X-Scanned-By: MIMEDefang 2.74 on 10.5.11.28 X-loop: libvir-list@redhat.com Subject: [libvirt] [PATCH v3] 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 --- 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 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 +principal is that every file, enum, struct, function, macro and typedef na= me +must have a 'vir' or 'VIR' prefix. All local scope variable names are exem= pt, +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 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, otherwise it sh= ould +match the filename. Following this comes the verb / action name, and final= ly +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 mo= re +uppercase words separated by underscores. The macro argument names should = be +in lowercase. Aside from having a "VIR" prefix there are no common practic= es +for the rest of the macro name. + + + + 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..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.

=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 principal is that every file, en= um, + 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. +

+
+
=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