From nobody Thu Mar 28 15:53:48 2024
Delivered-To: importer@patchew.org
Received-SPF: pass (zoho.com: domain of redhat.com designates 209.132.183.28
as permitted sender) client-ip=209.132.183.28;
envelope-from=libvir-list-bounces@redhat.com; helo=mx1.redhat.com;
Authentication-Results: mx.zohomail.com;
spf=pass (zoho.com: domain of redhat.com designates 209.132.183.28 as
permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com;
dmarc=pass(p=none dis=none) header.from=redhat.com
ARC-Seal: i=1; a=rsa-sha256; t=1557398624; cv=none;
d=zoho.com; s=zohoarc;
b=angtkB0fiveKRsHuqZQ4xG0zLjd51c6Fj3RNsXCqzAU8IB6gSP/BioBWO3tElgF1fM/g534Ga9+HNJ8pLyrBPQYSbeNqnFhID6+nNZtXuqOq8H63yYHYmh2IBcZ5oSp4QZ8sq3OVf9TaYVCySsY2FgMrHIdcl99N8Z0RqCngt+0=
ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zoho.com;
s=zohoarc;
t=1557398624;
h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To:ARC-Authentication-Results;
bh=RDsStRzgAo2oRS70kHKLxYYRNFrcBQH5+PzJjOAk4TU=;
b=cG/lJtwBfWwofP1I87XHYTxkz5o4UUi+O1Wb4tn1L3g0z4RypHwesRIhB5vvY8T+SzEatEcUW9Az9NZ6N95jL8XVyjrYrhRrjjr8Lsc5S7xaW+jYOYczf+IIwO/jXX6yfPfgir3F6abR3Z6Tc6mQUK1L72s5Tt0njSEZ1WOCmq0=
ARC-Authentication-Results: i=1; mx.zoho.com;
spf=pass (zoho.com: domain of redhat.com designates 209.132.183.28 as
permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com;
dmarc=pass header.from= (p=none dis=none)
header.from=
Return-Path:
Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) by
mx.zohomail.com
with SMTPS id 1557398624380745.6253630718827;
Thu, 9 May 2019 03:43:44 -0700 (PDT)
Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com
[10.5.11.23])
(using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits))
(No client certificate requested)
by mx1.redhat.com (Postfix) with ESMTPS id 4D9083087954;
Thu, 9 May 2019 10:43:42 +0000 (UTC)
Received: from colo-mx.corp.redhat.com
(colo-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.21])
by smtp.corp.redhat.com (Postfix) with ESMTPS id 754978919;
Thu, 9 May 2019 10:43:41 +0000 (UTC)
Received: from lists01.pubmisc.prod.ext.phx2.redhat.com
(lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33])
by colo-mx.corp.redhat.com (Postfix) with ESMTP id CDD9441F5A;
Thu, 9 May 2019 10:43:39 +0000 (UTC)
Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com
[10.5.11.16])
by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP
id x49Ahc3h029919 for ;
Thu, 9 May 2019 06:43:38 -0400
Received: by smtp.corp.redhat.com (Postfix)
id C037263C31; Thu, 9 May 2019 10:43:38 +0000 (UTC)
Received: from angien.brq.redhat.com (unknown [10.43.2.229])
by smtp.corp.redhat.com (Postfix) with ESMTP id 49CF261786
for ; Thu, 9 May 2019 10:43:38 +0000 (UTC)
From: Peter Krempa
To: libvir-list@redhat.com
Date: Thu, 9 May 2019 12:43:32 +0200
Message-Id:
<6fe473fa29478c302a44cbfcc3c931fdbb1e3aae.1557398401.git.pkrempa@redhat.com>
In-Reply-To:
References:
MIME-Version: 1.0
X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16
X-loop: libvir-list@redhat.com
Subject: [libvirt] [PATCH 1/3] docs: hacking: Document few practices for
creating error messages
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: ,
Content-Transfer-Encoding: quoted-printable
Sender: libvir-list-bounces@redhat.com
Errors-To: libvir-list-bounces@redhat.com
X-Scanned-By: MIMEDefang 2.84 on 10.5.11.23
X-Greylist: Sender IP whitelisted,
not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.45]);
Thu, 09 May 2019 10:43:42 +0000 (UTC)
Content-Type: text/plain; charset="utf-8"
State that error messages should not be broken into multiple lines for
programmer friendliness and should not be concatenated on the fly for
translator friendliness and few other details.
Signed-off-by: Peter Krempa
---
docs/hacking.html.in | 28 ++++++++++++++++++++++++++++
1 file changed, 28 insertions(+)
diff --git a/docs/hacking.html.in b/docs/hacking.html.in
index 902d05430f..081d793360 100644
--- a/docs/hacking.html.in
+++ b/docs/hacking.html.in
@@ -1284,6 +1284,34 @@
does for snprintf.
+
+
+
+ Error messages visible to the user should be short and descriptive. =
All
+ error messages are translated using gettext and thus must be wrapped=
in
+ _()
macro. To simplify the translation work, the error=
message
+ must not be concatenated from various parts. To simplify searching =
for
+ the error message in the code the strings should not be broken even
+ if they result into a line longer than 80 columns and any formatting
+ modifier should be enclosed by quotes or other obvious separator.
+ If a string used with %s
can be NULL the NULLSTR macro =
must
+ be used.
+
+
+
+ GOOD: virReportError(VIR_ERR_INTERNAL_ERROR,
+ _("Failed to connect to remote host '%s'"), hostnam=
e)
+
+ BAD: virReportError(VIR_ERR_INTERNAL_ERROR,
+ _("Failed to %s to remote host '%s'"),
+ "connect", hostname);
+
+ BAD: virReportError(VIR_ERR_INTERNAL_ERROR,
+ _("Failed to connect "
+ "to remote host '%s'),
+ hostname);
+
+
--=20
2.21.0
--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list
From nobody Thu Mar 28 15:53:48 2024
Delivered-To: importer@patchew.org
Received-SPF: pass (zoho.com: domain of redhat.com designates 209.132.183.28
as permitted sender) client-ip=209.132.183.28;
envelope-from=libvir-list-bounces@redhat.com; helo=mx1.redhat.com;
Authentication-Results: mx.zohomail.com;
spf=pass (zoho.com: domain of redhat.com designates 209.132.183.28 as
permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com;
dmarc=pass(p=none dis=none) header.from=redhat.com
ARC-Seal: i=1; a=rsa-sha256; t=1557398637; cv=none;
d=zoho.com; s=zohoarc;
b=RpOGdNBb9u90Yei0d1Sk4d+5a96PNSD0wUmBQS+qbRemJzv459atNuddiUXr2E0s9SQWyuqT8KbJfD02njusIGm5w8cj9tNa3mEADapkMxDKWfXL7wY7e4H+O/BR6Lb/acG8tsjOVGh+AB9mAqewDlknnDa1XhQ7cF0we9LyaTg=
ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zoho.com;
s=zohoarc;
t=1557398637;
h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To:ARC-Authentication-Results;
bh=qksLy6KAyikFw2olbx2vAghJl8SMjccC48iB0jEhx4c=;
b=DOBS8DssH7wvhdUZNZMymXd8QuWy/gnWK5fu91z9kua0fXnZDZpR8kBnaW/Qdv40hw6Gv86oiqDaVrfRTEb58cLPdLqyik64o0vdlktF7WtNJIAdIzpd4ZauuuVIO9Jg9qSpCo9+4n78WMvhgDVjlyqZUlTwwV5pSaRI+TOtjIE=
ARC-Authentication-Results: i=1; mx.zoho.com;
spf=pass (zoho.com: domain of redhat.com designates 209.132.183.28 as
permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com;
dmarc=pass header.from= (p=none dis=none)
header.from=
Return-Path:
Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) by
mx.zohomail.com
with SMTPS id 1557398637147840.6277551017054;
Thu, 9 May 2019 03:43:57 -0700 (PDT)
Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.phx2.redhat.com
[10.5.11.22])
(using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits))
(No client certificate requested)
by mx1.redhat.com (Postfix) with ESMTPS id 62739309B141;
Thu, 9 May 2019 10:43:55 +0000 (UTC)
Received: from colo-mx.corp.redhat.com
(colo-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.21])
by smtp.corp.redhat.com (Postfix) with ESMTPS id 3A6581001E74;
Thu, 9 May 2019 10:43:55 +0000 (UTC)
Received: from lists01.pubmisc.prod.ext.phx2.redhat.com
(lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33])
by colo-mx.corp.redhat.com (Postfix) with ESMTP id ED86B41F3D;
Thu, 9 May 2019 10:43:54 +0000 (UTC)
Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com
[10.5.11.16])
by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP
id x49Ahd0p029929 for ;
Thu, 9 May 2019 06:43:39 -0400
Received: by smtp.corp.redhat.com (Postfix)
id 8E34563C31; Thu, 9 May 2019 10:43:39 +0000 (UTC)
Received: from angien.brq.redhat.com (unknown [10.43.2.229])
by smtp.corp.redhat.com (Postfix) with ESMTP id 17F2961786
for ; Thu, 9 May 2019 10:43:38 +0000 (UTC)
From: Peter Krempa
To: libvir-list@redhat.com
Date: Thu, 9 May 2019 12:43:33 +0200
Message-Id:
<468fe5c3af5b52f3f23e60815f0a284e43466b41.1557398401.git.pkrempa@redhat.com>
In-Reply-To:
References:
MIME-Version: 1.0
X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16
X-loop: libvir-list@redhat.com
Subject: [libvirt] [PATCH 2/3] docs: hacking: Add good practices for
shortening conditional expressions
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: ,
Content-Transfer-Encoding: quoted-printable
Sender: libvir-list-bounces@redhat.com
Errors-To: libvir-list-bounces@redhat.com
X-Scanned-By: MIMEDefang 2.84 on 10.5.11.22
X-Greylist: Sender IP whitelisted,
not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.49]);
Thu, 09 May 2019 10:43:55 +0000 (UTC)
Content-Type: text/plain; charset="utf-8"
Document that checking if a integer is (non-)zero should (not must)
avoid the shortened form that C allows as it may confuse readers into
overlooking the other possible values which might be interresting to
handle.
While pointers have distinct values from the point of view of the code
we only care whether it's non-NULL and thus it's documented it's okay
to shorten those.
Signed-off-by: Peter Krempa
---
docs/hacking.html.in | 22 ++++++++++++++++++++++
1 file changed, 22 insertions(+)
diff --git a/docs/hacking.html.in b/docs/hacking.html.in
index 081d793360..a2800853ef 100644
--- a/docs/hacking.html.in
+++ b/docs/hacking.html.in
@@ -826,6 +826,28 @@
}
+
+ For readability reasons new code should avoid shortening comparis=
ons
+ to 0 for numeric types. Boolean and pointer comparisions may be
+ shortened. All long forms are okay:
+
+
+ virFooPtr foos =3D NULL;
+ size nfoos =3D 0;
+ bool hasFoos =3D false;
+
+GOOD:
+ if (!foos)
+ if (!hasFoos)
+ if (nfoos =3D=3D 0)
+ if (foos =3D=3D NULL)
+ if (hasFoos =3D=3D true)
+
+BAD:
+ if (!nfoos)
+ if (foos)
+
+
Macros defined with an ALL_CAPS name should generally be
--=20
2.21.0
--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list
From nobody Thu Mar 28 15:53:48 2024
Delivered-To: importer@patchew.org
Received-SPF: pass (zoho.com: domain of redhat.com designates 209.132.183.28
as permitted sender) client-ip=209.132.183.28;
envelope-from=libvir-list-bounces@redhat.com; helo=mx1.redhat.com;
Authentication-Results: mx.zohomail.com;
spf=pass (zoho.com: domain of redhat.com designates 209.132.183.28 as
permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com;
dmarc=pass(p=none dis=none) header.from=redhat.com
ARC-Seal: i=1; a=rsa-sha256; t=1557398640; cv=none;
d=zoho.com; s=zohoarc;
b=hH+yFMn/lowR29ta1c7Vt0+apS7rIIxjnr+ZFxTxcmhMssgWY+B1l9Qt2dnPNDraOtpDgXAKJi41U2rzCnNr2oVIzWOq6mnPHoAHBXQ7Eh1I2pSprfKTIWi2w1p/8dOK0WQE40t2kVTjkdpavBGp9sFNZuN2KVajO/dxFJ+XzjU=
ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zoho.com;
s=zohoarc;
t=1557398640;
h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To:ARC-Authentication-Results;
bh=ndjDXFwNGRELrnpZT2qYGa7MbrA9Wrc2f4Lj0xqmPws=;
b=a5NMZWeOHF1ixe4vVu3+EfDEFkDGnBrou6Yt3nPgeA0aAeDpyE6uOdaEvfexS6myWzaabQrvQiFpdFbzgpkZ7/7w9pcVWTIk8/df7l78Ii8Sh6/zYiZu8hCzbVzP+xcqRKJXWPpP/SEo1Pi1roG7PUw7fK3YgTs21en0njzVV74=
ARC-Authentication-Results: i=1; mx.zoho.com;
spf=pass (zoho.com: domain of redhat.com designates 209.132.183.28 as
permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com;
dmarc=pass header.from= (p=none dis=none)
header.from=
Return-Path:
Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) by
mx.zohomail.com
with SMTPS id 1557398640469344.3114353645333;
Thu, 9 May 2019 03:44:00 -0700 (PDT)
Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.phx2.redhat.com
[10.5.11.22])
(using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits))
(No client certificate requested)
by mx1.redhat.com (Postfix) with ESMTPS id DE2E0306E5FB;
Thu, 9 May 2019 10:43:58 +0000 (UTC)
Received: from colo-mx.corp.redhat.com
(colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20])
by smtp.corp.redhat.com (Postfix) with ESMTPS id B8CEF1001E81;
Thu, 9 May 2019 10:43:58 +0000 (UTC)
Received: from lists01.pubmisc.prod.ext.phx2.redhat.com
(lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33])
by colo-mx.corp.redhat.com (Postfix) with ESMTP id 7E40418089CB;
Thu, 9 May 2019 10:43:58 +0000 (UTC)
Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com
[10.5.11.16])
by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP
id x49Ahe3m029934 for ;
Thu, 9 May 2019 06:43:40 -0400
Received: by smtp.corp.redhat.com (Postfix)
id 5BA2063C31; Thu, 9 May 2019 10:43:40 +0000 (UTC)
Received: from angien.brq.redhat.com (unknown [10.43.2.229])
by smtp.corp.redhat.com (Postfix) with ESMTP id DA96461786
for ; Thu, 9 May 2019 10:43:39 +0000 (UTC)
From: Peter Krempa
To: libvir-list@redhat.com
Date: Thu, 9 May 2019 12:43:34 +0200
Message-Id:
In-Reply-To:
References:
MIME-Version: 1.0
X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16
X-loop: libvir-list@redhat.com
Subject: [libvirt] [PATCH 3/3] docs: hacking: Discourage use of the ternary
operator and ban it's abuse
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: ,
Content-Transfer-Encoding: quoted-printable
Sender: libvir-list-bounces@redhat.com
Errors-To: libvir-list-bounces@redhat.com
X-Scanned-By: MIMEDefang 2.84 on 10.5.11.22
X-Greylist: Sender IP whitelisted,
not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.49]);
Thu, 09 May 2019 10:43:59 +0000 (UTC)
Content-Type: text/plain; charset="utf-8"
Forbid breaking lines inside the two branches of the ternary operator
and nesting them. Using it in these instances does not help readability.
Signed-off-by: Peter Krempa
---
docs/hacking.html.in | 11 +++++++++++
1 file changed, 11 insertions(+)
diff --git a/docs/hacking.html.in b/docs/hacking.html.in
index a2800853ef..fc4adae354 100644
--- a/docs/hacking.html.in
+++ b/docs/hacking.html.in
@@ -847,6 +847,17 @@ BAD:
if (!nfoos)
if (foos)
+ New code should avoid the ternary operator as much as possible.
+ Specifically it must never span more than one line or nest:
+
+
+BAD:
+ char *foo =3D baz ?
+ virDoSomethingReallyComplex(driver, vm, something, baz->fo=
o) :
+ NULL;
+
+ char *foo =3D bar ? bar->baz ? bar->baz->foo : "nobaz" : "nobar";
+
--=20
2.21.0
--
libvir-list mailing list
libvir-list@redhat.com
https://www.redhat.com/mailman/listinfo/libvir-list