From owner-cvs-all  Wed Aug 21 20:13:29 2002
Delivered-To: cvs-all@freebsd.org
Received: from mx1.FreeBSD.org (mx1.FreeBSD.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP
	id 91F5B37B400; Wed, 21 Aug 2002 20:13:22 -0700 (PDT)
Received: from mailman.zeta.org.au (mailman.zeta.org.au [203.26.10.16])
	by mx1.FreeBSD.org (Postfix) with ESMTP
	id 18B4E43E65; Wed, 21 Aug 2002 20:13:21 -0700 (PDT)
	(envelope-from bde@zeta.org.au)
Received: from bde.zeta.org.au (bde.zeta.org.au [203.2.228.102])
	by mailman.zeta.org.au (8.9.3/8.8.7) with ESMTP id DAA16219;
	Thu, 22 Aug 2002 03:13:15 GMT
Date: Thu, 22 Aug 2002 13:19:43 +1000 (EST)
From: Bruce Evans <bde@zeta.org.au>
X-X-Sender: bde@gamplex.bde.org
To: Garrett Wollman <wollman@lcs.mit.edu>
Cc: Warner Losh <imp@FreeBSD.org>, <cvs-committers@FreeBSD.org>,
	<cvs-all@FreeBSD.org>
Subject: Re: cvs commit: src/share/man/man9 style.9
In-Reply-To: <200208211833.g7LIXAv0001530@khavrinen.lcs.mit.edu>
Message-ID: <20020822131207.D2039-100000@gamplex.bde.org>
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII
Sender: owner-cvs-all@FreeBSD.ORG
Precedence: bulk
List-ID: <cvs-all.FreeBSD.ORG>
List-Archive: <http://docs.freebsd.org/mail/> (Web Archive)
List-Help: <mailto:majordomo@FreeBSD.ORG?subject=help> (List Instructions)
List-Subscribe: <mailto:majordomo@FreeBSD.ORG?subject=subscribe%20cvs-all>
List-Unsubscribe: <mailto:majordomo@FreeBSD.ORG?subject=unsubscribe%20cvs-all>
X-Loop: FreeBSD.ORG

On Wed, 21 Aug 2002, Garrett Wollman wrote:

> <<On Tue, 20 Aug 2002 23:58:22 -0700 (PDT), Warner Losh <imp@FreeBSD.org> said:
>
> >   Suggest that function prototypes in kernel headers be alphabetical,
> >   unless there's a compelling reason to deviate.
>
> It should probably suggest that prototypes visible to user programs be
> first blocked in order of increasing namespace before being
> alphabetized.  It is more readable to have:
>
> 	#if FOO_AND_BAR_VISIBLE
> 	int bar(...);
> 	int foo(...);
> 	#endif
>
> 	#if BAZ_VISIBLE
> 	int baz(...);
> 	#endif
>
> 	#if FOO_BAR_AND_QUUX_VISIBLE
> 	int quux(...);
> 	#endif
>
> ...rather than:
>
> 	#if FOO_AND_BAR_VISIBLE
> 	int bar(...);
> 	#endif
> 	#if BAZ_VISIBLE
> 	int baz(...);
> 	#endif
> 	#if FOO_AND_BAR_VISIBLE
> 	int foo(...);
> 	#if FOO_BAR_AND_QUUX_VISIBLE
> 	int quux(...);
> 	#endif
> 	#endif

I mostly disagree.  I find the former slightly more readable (except for
the nested ifdef in the latter).

POSIX.1-200x-draft7 lists things in alphabetical order within headers
and uses markup like "XSI" (and highlighing in the pdf version?) to
show extensions.  This keeps related things together provided the
function names are well chosen.

Bruce


To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe cvs-all" in the body of the message