[libvirt PATCH v3 0/2] Code style documentation
Some additions and clarifications to libvirt's code style documentation, based on points of feedback that are given regularly on the mailing list. V1: https://listman.redhat.com/archives/libvir-list/2022-January/msg00631.html V2: https://listman.redhat.com/archives/libvir-list/2022-January/msg00681.html Changes since V2: * Changed the example type name in patch 1 Tim Wiederhake (2): docs: coding-style: Clarify on virXXXPtr types docs: coding-style: One variable declaration per line docs/coding-style.rst | 28 +++++++++++++++++++++++----- 1 file changed, 23 insertions(+), 5 deletions(-) -- 2.31.1
This partially reverts commit 9ccbed6afb. Signed-off-by: Tim Wiederhake <twiederh@redhat.com> --- docs/coding-style.rst | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/docs/coding-style.rst b/docs/coding-style.rst index 37e6009db4..af928a16c0 100644 --- a/docs/coding-style.rst +++ b/docs/coding-style.rst @@ -53,11 +53,16 @@ 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. + name with a leading underscore. For types that are part of the + public API, a second typedef should be given for a pointer to + the struct with a 'Ptr' suffix. Do not introduce new such + typedefs for internal types. + :: - typedef struct _virHashTable virHashTable; - struct _virHashTable { + typedef struct _virSomeType virSomeType; + typedef virSomeType *virSomeTypePtr; + struct _virSomeType { ... }; @@ -69,8 +74,8 @@ Function names 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. + given an object 'virSomeType', all functions should have a + name 'virSomeType$VERB' or 'virSomeType$VERB$SUBJECT", e.g. 'virHashTableLookup' or 'virHashTableGetValue'. Macro names -- 2.31.1
This was not mentioned before. Signed-off-by: Tim Wiederhake <twiederh@redhat.com> --- docs/coding-style.rst | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/coding-style.rst b/docs/coding-style.rst index af928a16c0..cb23751721 100644 --- a/docs/coding-style.rst +++ b/docs/coding-style.rst @@ -600,6 +600,19 @@ calling another function. ... } +Prefer variable definitions on separate lines. This allows for smaller, +easier to understand diffs when changing them. Define variables in the +smallest possible scope. + +:: + + GOOD: + int count = 0; + int nnodes; + + BAD: + int count = 0, nnodes; + Attribute annotations --------------------- -- 2.31.1
On Wed, Jan 19, 2022 at 11:06:52 +0100, Tim Wiederhake wrote:
Some additions and clarifications to libvirt's code style documentation, based on points of feedback that are given regularly on the mailing list.
V1: https://listman.redhat.com/archives/libvir-list/2022-January/msg00631.html V2: https://listman.redhat.com/archives/libvir-list/2022-January/msg00681.html
Changes since V2: * Changed the example type name in patch 1
Tim Wiederhake (2): docs: coding-style: Clarify on virXXXPtr types docs: coding-style: One variable declaration per line
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
On a Wednesday in 2022, Tim Wiederhake wrote:
Some additions and clarifications to libvirt's code style documentation, based on points of feedback that are given regularly on the mailing list.
V1: https://listman.redhat.com/archives/libvir-list/2022-January/msg00631.html V2: https://listman.redhat.com/archives/libvir-list/2022-January/msg00681.html
Changes since V2: * Changed the example type name in patch 1
Tim Wiederhake (2): docs: coding-style: Clarify on virXXXPtr types docs: coding-style: One variable declaration per line
docs/coding-style.rst | 28 +++++++++++++++++++++++----- 1 file changed, 23 insertions(+), 5 deletions(-)
Reviewed-by: Ján Tomko <jtomko@redhat.com> Jano
On Wed, Jan 19, 2022 at 11:06:52AM +0100, Tim Wiederhake wrote:
Some additions and clarifications to libvirt's code style documentation, based on points of feedback that are given regularly on the mailing list.
V1: https://listman.redhat.com/archives/libvir-list/2022-January/msg00631.html V2: https://listman.redhat.com/archives/libvir-list/2022-January/msg00681.html
Changes since V2: * Changed the example type name in patch 1
Tim Wiederhake (2): docs: coding-style: Clarify on virXXXPtr types docs: coding-style: One variable declaration per line
Reviewed-by: Andrea Bolognani <abologna@redhat.com> -- Andrea Bolognani / Red Hat / Virtualization
On 1/19/22 11:06, Tim Wiederhake wrote:
Some additions and clarifications to libvirt's code style documentation, based on points of feedback that are given regularly on the mailing list.
V1: https://listman.redhat.com/archives/libvir-list/2022-January/msg00631.html V2: https://listman.redhat.com/archives/libvir-list/2022-January/msg00681.html
Changes since V2: * Changed the example type name in patch 1
Tim Wiederhake (2): docs: coding-style: Clarify on virXXXPtr types docs: coding-style: One variable declaration per line
docs/coding-style.rst | 28 +++++++++++++++++++++++----- 1 file changed, 23 insertions(+), 5 deletions(-)
Reviewed-by: Michal Privoznik <mprivozn@redhat.com> Michal
On Wed, Jan 19, 2022 at 11:06:52AM +0100, Tim Wiederhake wrote:
Some additions and clarifications to libvirt's code style documentation, based on points of feedback that are given regularly on the mailing list.
V1: https://listman.redhat.com/archives/libvir-list/2022-January/msg00631.html V2: https://listman.redhat.com/archives/libvir-list/2022-January/msg00681.html
Changes since V2: * Changed the example type name in patch 1
Tim Wiederhake (2): docs: coding-style: Clarify on virXXXPtr types docs: coding-style: One variable declaration per line
docs/coding-style.rst | 28 +++++++++++++++++++++++----- 1 file changed, 23 insertions(+), 5 deletions(-)
--
Reviewed-by: Martin Kletzander <mkletzan@redhat.com>
On Wed, Jan 19, 2022 at 11:06:52AM +0100, Tim Wiederhake wrote:
Some additions and clarifications to libvirt's code style documentation, based on points of feedback that are given regularly on the mailing list.
V1: https://listman.redhat.com/archives/libvir-list/2022-January/msg00631.html V2: https://listman.redhat.com/archives/libvir-list/2022-January/msg00681.html
Changes since V2: * Changed the example type name in patch 1
Tim Wiederhake (2): docs: coding-style: Clarify on virXXXPtr types docs: coding-style: One variable declaration per line
Reviewed-by: Pavel Hrdina <phrdina@redhat.com>
participants (7)
-
Andrea Bolognani -
Ján Tomko -
Martin Kletzander -
Michal Prívozník -
Pavel Hrdina -
Peter Krempa -
Tim Wiederhake