From mwm@mired.org  Sat Jun 30 14:27:01 2001
Return-Path: <mwm@mired.org>
Received: from guru.mired.org (okc-27-141-144.mmcable.com [24.27.141.144])
	by hub.freebsd.org (Postfix) with SMTP id 7B9D437B406
	for <FreeBSD-gnats-submit@freebsd.org>; Sat, 30 Jun 2001 14:27:00 -0700 (PDT)
	(envelope-from mwm@mired.org)
Received: (qmail 72820 invoked by uid 100); 30 Jun 2001 21:26:59 -0000
Message-Id: <20010630212659.72819.qmail@guru.mired.org>
Date: 30 Jun 2001 21:26:59 -0000
From: Mike Meyer <mwm@mired.org>
Reply-To: Mike Meyer <mwm@mired.org>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: [PATCH] style(9) isn't explicit about booleans for testing.
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         28555
>Category:       docs
>Synopsis:       [PATCH] style(9) isn't explicit about booleans for testing.
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    trhodes
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          change-request
>Submitter-Id:   current-users
>Arrival-Date:   Sat Jun 30 14:30:01 PDT 2001
>Closed-Date:    Fri Jul 07 03:36:27 GMT 2006
>Last-Modified:  Fri Jul 07 03:36:27 GMT 2006
>Originator:     Mike Meyer
>Release:        FreeBSD 4.3-STABLE i386
>Organization:
Meyer Consulting
>Environment:
System: FreeBSD guru.mired.org 4.3-STABLE FreeBSD 4.3-STABLE #22: Sun Jun 24 13:15:49 CDT 2001 mwm@guru.mired.org:/sharetmp/obj/usr/src/sys/GURU i386

>Description:

The style(9) page says not to use ! for testing values unless the
value is a boolean. It also says to test pointers against NULL. This
leaves open the question of how other values that aren't booleans
should be tested.

>How-To-Repeat:

Read the man page to try and decide if you should write "if (x)" or
if (x != 0).

>Fix:

Apply the attached page to the style(9) man page.

--- /usr/src/share/man/man9/style.9	Fri May 18 07:27:37 2001
+++ style.9	Sat Jun 30 16:23:34 2001
@@ -449,14 +449,37 @@
 !(p = f())
 .Ed
 .Pp
-Don't use '!' for tests unless it's a boolean, e.g. use
+For tests, always compare the value to the appropriate 0 instead of
+checking it directly, unless the value is a boolean.
+For pointers, use:
+.Bd -literal
+if (p != NULL)
+.Ed
+.Pp
+not
+.PP
+.Bd -literal
+if (!p)
+.Ed
+.Pp
+For other values, use:
 .Bd -literal
 if (*p == '\e0')
 .Ed
 .Pp
 not
 .Bd -literal
-if (!*p)
+if (*p)
+.Ed
+.Pp
+unless the value is a boolean. In that case, use:
+.Bd -literal
+if (p)
+.Ed
+.Pp
+and
+.Bd -literal
+if (!p)
 .Ed
 .Pp
 Routines returning void * should not have their return values cast

>Release-Note:
>Audit-Trail:

From: Dima Dorfman <dima@unixfreak.org>
To: Mike Meyer <mwm@mired.org>
Cc: FreeBSD-gnats-submit@freebsd.org
Subject: Re: docs/28555: [PATCH] style(9) isn't explicit about booleans for testing. 
Date: Sat, 30 Jun 2001 14:57:49 -0700

 Mike Meyer <mwm@mired.org> writes:
 > 
 > >Number:         28555
 > >Category:       docs
 > >Synopsis:       [PATCH] style(9) isn't explicit about booleans for testing.
 > >Description:
 > 
 > The style(9) page says not to use ! for testing values unless the
 > value is a boolean. It also says to test pointers against NULL. This
 > leaves open the question of how other values that aren't booleans
 > should be tested.
 > 
 > >How-To-Repeat:
 > 
 > Read the man page to try and decide if you should write "if (x)" or
 > if (x != 0).
 
 I think it is quite clear on the subject.  If it's not a boolean,
 don't treat it like one; i.e., compare it against the value you're
 looking for.  '0' may not always be that value.
 
 Regardless, this does not belong as a PR, let alone in the docs/
 category.  It belongs as a post on -hackers, asking what people think,
 not as a change request.  Since *developers* are expected to follow
 style(9), it is the *developers* (i.e., -hackers@) that you should be
 proposing the change to.
 
 					Dima Dorfman
 					dima@unixfreak.org

From: Mike Meyer <mwm@mired.org>
To: Dima Dorfman <dima@unixfreak.org>
Cc: FreeBSD-gnats-submit@freebsd.org
Subject: Re: docs/28555: [PATCH] style(9) isn't explicit about booleans for testing. 
Date: Sat, 30 Jun 2001 17:55:10 -0500

 Dima Dorfman <dima@unixfreak.org> types:
 > Mike Meyer <mwm@mired.org> writes:
 > > 
 > > >Number:         28555
 > > >Category:       docs
 > > >Synopsis:       [PATCH] style(9) isn't explicit about booleans for testing.
 > > >Description:
 > > 
 > > The style(9) page says not to use ! for testing values unless the
 > > value is a boolean. It also says to test pointers against NULL. This
 > > leaves open the question of how other values that aren't booleans
 > > should be tested.
 > > 
 > > >How-To-Repeat:
 > > 
 > > Read the man page to try and decide if you should write "if (x)" or
 > > if (x != 0).
 > I think it is quite clear on the subject.  If it's not a boolean,
 > don't treat it like one; i.e., compare it against the value you're
 > looking for.  '0' may not always be that value.
 
 I did overstated the case in the description. I agree that it's clear
 on the subject; I think it needs to be made explicit.
 
 > Regardless, this does not belong as a PR, let alone in the docs/
 > category.  It belongs as a post on -hackers, asking what people think,
 > not as a change request.  Since *developers* are expected to follow
 > style(9), it is the *developers* (i.e., -hackers@) that you should be
 > proposing the change to.
 
 We both agree I'm not proposing a change in the style they have to
 follow; I'm just proposing making something explicit instead of
 implicit. As such, I'm not sure it warrants discussion. If the PR
 belongs in another category, please feel free to move it to either
 move it or suggest one for someone else to move it to.
 
 	Thanx,
 	<mike
 --
 Mike Meyer <mwm@mired.org>			http://www.mired.org/home/mwm/
 Independent WWW/Perforce/FreeBSD/Unix consultant, email for more information.

From: Dima Dorfman <dima@unixfreak.org>
To: Mike Meyer <mwm@mired.org>
Cc: FreeBSD-gnats-submit@freebsd.org
Subject: Re: docs/28555: [PATCH] style(9) isn't explicit about booleans for testing. 
Date: Mon, 02 Jul 2001 16:13:26 -0700

 Mike Meyer <mwm@mired.org> writes:
 > Dima Dorfman <dima@unixfreak.org> types:
 > > Regardless, this does not belong as a PR, let alone in the docs/
 > > category.  It belongs as a post on -hackers, asking what people think,
 > > not as a change request.  Since *developers* are expected to follow
 > > style(9), it is the *developers* (i.e., -hackers@) that you should be
 > > proposing the change to.
 > 
 > We both agree I'm not proposing a change in the style they have to
 > follow; I'm just proposing making something explicit instead of
 > implicit. As such, I'm not sure it warrants discussion.
 
 I'm not suggesting that you should get every developer's approval, but
 I am suggesting that wider review than the -doc list would be nice,
 esp. for a document that defines policy.
 
 					Dima Dorfman
 					dima@unixfreak.org
Responsible-Changed-From-To: freebsd-doc->trhodes 
Responsible-Changed-By: trhodes 
Responsible-Changed-When: Wed Nov 6 20:57:58 PST 2002 
Responsible-Changed-Why:  
I'll take this. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=28555 
State-Changed-From-To: open->closed 
State-Changed-By: trhodes 
State-Changed-When: Fri Jul 7 03:33:46 UTC 2006 
State-Changed-Why:  
This should have been closed a good while ago.  We do not 
need an example of every type of 0.  Furthermore, the current 
version of style(9) is correct and the suggested patch seems 
to be getting the tests in both of the examples backwards 
starting from a non-backwards example of '0'. 

If wording is that large of an issue, please bring it up 
on the mailing lists.  Thanks! 

http://www.freebsd.org/cgi/query-pr.cgi?pr=28555 
>Unformatted:
