From 27dfb0280ff87f61978befc1f7dd72b7d3ab93d9 Mon Sep 17 00:00:00 2001
From: Peter Krempa <pkrempa@redhat.com>
Date: Thu, 9 May 2019 12:20:42 +0200
Subject: [PATCH] docs: hacking: Add good practices for shortening conditional
 expressions

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 <pkrempa@redhat.com>
ACKed-by: Eric Blake <eblake@redhat.com>
---
 docs/hacking.html.in | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/docs/hacking.html.in b/docs/hacking.html.in
index 081d793360..1f82c668e5 100644
--- a/docs/hacking.html.in
+++ b/docs/hacking.html.in
@@ -826,6 +826,28 @@
   }
 </pre>
 
+    <h2><a id="conditions">Conditional expressions</a></h2>
+      <p>For readability reasons new code should avoid shortening comparisons
+        to 0 for numeric types. Boolean and pointer comparisions may be
+        shortened. All long forms are okay:
+      </p>
+<pre>
+   virFooPtr foos = NULL;
+   size nfoos = 0;
+   bool hasFoos = false;
+
+GOOD:
+    if (!foos)
+    if (!hasFoos)
+    if (nfoos == 0)
+    if (foos == NULL)
+    if (hasFoos == true)
+
+BAD:
+    if (!nfoos)
+    if (nfoos)
+</pre>
+
     <h2><a id="preprocessor">Preprocessor</a></h2>
 
     <p>Macros defined with an ALL_CAPS name should generally be
-- 
GitLab