[gnome-devel-docs/wip/swilmet/prog-guidelines] programming-guidelines: improve section on conditions coding style

[Sébastien Wilmet <swilmet src gnome org>]

commit 3b993c78a1afcca96d811f2af8bf7695f6500b23
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Fri Nov 6 16:36:35 2015 +0100

    programming-guidelines: improve section on conditions coding style
    
    - Add one more rationale for boolean implicit comparisons
      (conversational English).
    - Generalize comparisons to NULL -> comparisons to 0 values, and give
      better reasons than porting the code to C#.
    - Fix the indentation of the paragraphs.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=757692

 programming-guidelines/C/c-coding-style.page |   62 ++++++++++++++++++-------
 1 files changed, 44 insertions(+), 18 deletions(-)
---
diff --git a/programming-guidelines/C/c-coding-style.page b/programming-guidelines/C/c-coding-style.page
index e3710e8..226a4c1 100644
--- a/programming-guidelines/C/c-coding-style.page
+++ b/programming-guidelines/C/c-coding-style.page
@@ -388,40 +388,66 @@ my_function (int argument)
     <title>Conditions</title>
 
     <p>
-      Do not check boolean values for equality.  The rationale is that
-      a ‘true’ value may not be necessarily equal to whatever the
-      <code>TRUE</code> macro uses.  For example:
+      Do not check boolean values for equality.  By using implicit
+      comparisons, the resulting code can be read more like conversational
+      English.  Another rationale is that a ‘true’ value may not be necessarily
+      equal to whatever the <code>TRUE</code> macro uses.  For example:
     </p>
 
     <code style="invalid">
 /* invalid */
-if (condition == TRUE)
-       do_foo ();</code>
+if (found == TRUE)
+       do_foo ();
+
+/* invalid */
+if (found == FALSE)
+       do_bar ();</code>
+
+    <code style="valid">
+/* valid */
+if (found)
+       do_foo ();
 
-<code style="valid">
 /* valid */
-if (another_condition)
+if (!found)
        do_bar ();</code>
 
-        <p>
-          Even if C handles <code>NULL</code> equality like a boolean, be
-          explicit. This makes it easier to port your C code to something like
-          C#, where testing against null explicitly is important:
-        </p>
+    <p>
+      The C language uses the value 0 for many purposes.  As a numeric value,
+      the end of a string, a null pointer and the <code>FALSE</code> boolean.
+      To make the code clearer, you should write code that highlights the
+      specific way 0 is used.  So when reading a comparison, it is possible to
+      know the variable type.  For boolean variables, an implicit comparison is
+      appropriate because it's already a logical expression.  Other variable
+      types are not logical expressions by themselves, so an explicit
+      comparison is better:
+    </p>
 
-        <code style="valid">
+    <code style="valid">
 /* valid */
 if (some_pointer == NULL)
        do_blah ();
 
 /* valid */
-if (something != NULL)
-       do_foo ();</code>
+if (number == 0)
+       do_foo ();
 
-<code style="invalid">
+/* valid */
+if (str != NULL &amp;&amp; *str != '\0')
+       do_bar ();</code>
+
+    <code style="invalid">
 /* invalid */
-if (some_other_pointer)
-       do_blurp ();</code>
+if (!some_pointer)
+       do_blah ();
+
+/* invalid */
+if (!number)
+       do_foo ();
+
+/* invalid */
+if (str &amp;&amp; *str)
+       do_bar ();</code>
   </section>
 
   <section id="functions">