From unknown Tue Jun 24 05:13:28 2025 X-Loop: help-debbugs@gnu.org Subject: bug#5951: [PATCH] doc: document our code formatting policy regarding curly braces Resent-From: Jim Meyering Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-To: owner@debbugs.gnu.org Resent-CC: bug-coreutils@gnu.org Resent-Date: Thu, 15 Apr 2010 08:24:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 5951 X-GNU-PR-Package: coreutils X-GNU-PR-Keywords: patch To: 5951@debbugs.gnu.org X-Debbugs-Original-To: bug-coreutils@gnu.org Received: via spool by submit@debbugs.gnu.org id=B.12713197923108 (code B ref -1); Thu, 15 Apr 2010 08:24:02 +0000 Received: (at submit) by debbugs.gnu.org; 15 Apr 2010 08:23:12 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1O2KLw-0000o5-Ah for submit@debbugs.gnu.org; Thu, 15 Apr 2010 04:23:12 -0400 Received: from mx10.gnu.org ([199.232.76.166]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1O2KLs-0000nz-Le for submit@debbugs.gnu.org; Thu, 15 Apr 2010 04:23:09 -0400 Received: from lists.gnu.org ([199.232.76.165]:60709) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1O2KLp-0004Aw-Jd for submit@debbugs.gnu.org; Thu, 15 Apr 2010 04:23:05 -0400 Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1O2KLo-0006ex-T8 for bug-coreutils@gnu.org; Thu, 15 Apr 2010 04:23:04 -0400 Received: from [140.186.70.92] (port=35571 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1O2KLj-0006el-Pj for bug-coreutils@gnu.org; Thu, 15 Apr 2010 04:23:04 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.0 (2010-01-18) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-1.9 required=5.0 tests=BAYES_00,RCVD_IN_DNSWL_NONE autolearn=unavailable version=3.3.0 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1O2KLh-00023g-OZ for bug-coreutils@gnu.org; Thu, 15 Apr 2010 04:22:59 -0400 Received: from smtp3-g21.free.fr ([212.27.42.3]:56997) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1O2KLh-000239-5L for bug-coreutils@gnu.org; Thu, 15 Apr 2010 04:22:57 -0400 Received: from smtp3-g21.free.fr (localhost [127.0.0.1]) by smtp3-g21.free.fr (Postfix) with ESMTP id 63B19818047 for ; Thu, 15 Apr 2010 10:22:51 +0200 (CEST) Received: from mx.meyering.net (mx.meyering.net [82.230.74.64]) by smtp3-g21.free.fr (Postfix) with ESMTP id 764208181AB for ; Thu, 15 Apr 2010 10:22:49 +0200 (CEST) Received: by rho.meyering.net (Acme Bit-Twister, from userid 1000) id 311DDC46; Thu, 15 Apr 2010 10:22:49 +0200 (CEST) From: Jim Meyering Date: Thu, 15 Apr 2010 10:22:49 +0200 Message-ID: <87wrw9azvq.fsf@meyering.net> Lines: 140 MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) X-detected-operating-system: by monty-python.gnu.org: GNU/Linux 2.6, seldom 2.4 (older, 4) X-Spam-Score: -3.8 (---) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -5.1 (-----) Hello, I was burned by a multi-line single-stmt (no braces) loop body in libvirt yesterday: http://thread.gmane.org/gmane.comp.emulators.libvirt/23715 and that has prompted me to write the following, which codifies my personal policy/practice. It may be derived from the GCS, but I haven't checked yet. Any suggestions or comments before I push? >From a7d51ecb8ea2788081a23f1dce4eb0d503c02ce4 Mon Sep 17 00:00:00 2001 From: Jim Meyering Date: Thu, 15 Apr 2010 10:17:47 +0200 Subject: [PATCH] doc: document our code formatting policy regarding curly braces * HACKING (Curly braces: use judiciously): New section. --- HACKING | 104 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 104 insertions(+), 0 deletions(-) diff --git a/HACKING b/HACKING index 124c666..7ccd2be 100644 --- a/HACKING +++ b/HACKING @@ -233,6 +233,110 @@ Try to make the summary line fit one of the following forms: maint: change-description +Curly braces: use judiciously +============================= +Omit the curly braces around an "if", "while", "for" etc. body only when +that body occupies a single line. In every other case we require the braces. +This ensures that it is trivially easy to identify a single-*statement* loop: +each has only one *line* in its body. + +For example, do not omit the curly braces even when the body is just a +single-line statement but with a preceding comment. + +Omitting braces with a single-line body is fine: + + while (expr) + single_line_stmt (); + +However, the moment your loop/if/else body extends onto a second line, +for whatever reason (even if it's just an added comment), then you should +add braces. Otherwise, it would be too easy to insert a statement just +before that comment (without adding braces), thinking it is already a +multi-statement loop: + + while (true) + /* comment... */ // BAD: multi-line body without braces + single_line_stmt (); + +Do this instead: + + while (true) + { /* Always put braces around a multi-line body. */ + /* explanation... */ + single_line_stmt (); + } + +There is one exception: when the second body line is not +at the same indentation level as the first body line. + + if (expr) + error (0, 0, _("a diagnostic that would make this line" + " extend past the 80-column limit")); + +It seems safe not to require curly braces in this case, +since the further-indented second body line makes it obvious +that this is still a single-statement body. + +To reiterate, don't do this: + + if (expr) + while (expr_2) // BAD: multi-line body without braces + { + ... + } + +Do this, instead: + + if (expr) + { + while (expr_2) + { + ... + } + } + +However, there is one exception in the other direction, when +even a one-line block should have braces. +That occurs when that one-line, brace-less block +is an "else" block, and the corresponding "then" block *does* use braces. +In that case, either put braces around the "else" block, or negate the +"if"-condition and swap the bodies, putting the one-line block first +and making the longer, multi-line block be the "else" block. + + if (expr) + { + ... + ... + } + else + x = y; // BAD: braceless "else" with braced "then" + +This is preferred, especially when the multi-line body is more +than a few lines long, because it is easier to read and grasp +the semantics of an if-then-else block when the simpler block +occurs first, rather than after the more involved block: + + if (!expr) + x = y; /* more readable */ + else + { + ... + ... + } + +If you'd rather not negate the condition, then add braces: + + if (expr) + { + ... + ... + } + else + { + x = y; + } + + Use SPACE-only indentation in all[*] files ========================================== We use space-only indentation in nearly all files. -- 1.7.1.rc1.248.gcefbb From unknown Tue Jun 24 05:13:28 2025 X-Loop: help-debbugs@gnu.org Subject: bug#5951: [PATCH] doc: document our code formatting policy regarding curly braces Resent-From: Eric Blake Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-To: owner@debbugs.gnu.org Resent-CC: bug-coreutils@gnu.org Resent-Date: Thu, 15 Apr 2010 14:04:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 5951 X-GNU-PR-Package: coreutils X-GNU-PR-Keywords: patch To: Jim Meyering Cc: 5951@debbugs.gnu.org Received: via spool by 5951-submit@debbugs.gnu.org id=B5951.127134023714309 (code B ref 5951); Thu, 15 Apr 2010 14:04:02 +0000 Received: (at 5951) by debbugs.gnu.org; 15 Apr 2010 14:03:57 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1O2Pfg-0003ik-P1 for submit@debbugs.gnu.org; Thu, 15 Apr 2010 10:03:57 -0400 Received: from mx1.redhat.com ([209.132.183.28]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1O2Pfe-0003if-QL for 5951@debbugs.gnu.org; Thu, 15 Apr 2010 10:03:56 -0400 Received: from int-mx03.intmail.prod.int.phx2.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.16]) by mx1.redhat.com (8.13.8/8.13.8) with ESMTP id o3FE3mrg002558 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Thu, 15 Apr 2010 10:03:49 -0400 Received: from [10.11.8.229] (vpn-8-229.rdu.redhat.com [10.11.8.229]) by int-mx03.intmail.prod.int.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id o3FE3lm7022089; Thu, 15 Apr 2010 10:03:47 -0400 Message-ID: <4BC71CCA.3030907@redhat.com> Date: Thu, 15 Apr 2010 08:03:54 -0600 From: Eric Blake Organization: Red Hat User-Agent: Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.9.1.9) Gecko/20100330 Fedora/3.0.4-1.fc12 Lightning/1.0b1 Thunderbird/3.0.4 MIME-Version: 1.0 References: <87wrw9azvq.fsf@meyering.net> In-Reply-To: <87wrw9azvq.fsf@meyering.net> X-Enigmail-Version: 1.0.1 Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="------------enig6CF19E5285445A96AE7667E3" X-Scanned-By: MIMEDefang 2.67 on 10.5.11.16 X-Spam-Score: -10.3 (----------) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -10.3 (----------) This is an OpenPGP/MIME signed message (RFC 2440 and 3156) --------------enig6CF19E5285445A96AE7667E3 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable On 04/15/2010 02:22 AM, Jim Meyering wrote: > Hello, >=20 > I was burned by a multi-line single-stmt (no braces) loop body > in libvirt yesterday: >=20 > http://thread.gmane.org/gmane.comp.emulators.libvirt/23715 >=20 > and that has prompted me to write the following, > which codifies my personal policy/practice. It may > be derived from the GCS, but I haven't checked yet. >=20 > Any suggestions or comments before I push? Looks good, except: > +Curly braces: use judiciously > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D > +Omit the curly braces around an "if", "while", "for" etc. body only wh= en > +that body occupies a single line. In every other case we require the = braces. > +This ensures that it is trivially easy to identify a single-*statement= * loop: > +each has only one *line* in its body. > + > +For example, do not omit the curly braces even when the body is just a= > +single-line statement but with a preceding comment. the paragraph above... > + > +Omitting braces with a single-line body is fine: > + > + while (expr) > + single_line_stmt (); > + > +However, the moment your loop/if/else body extends onto a second line,= > +for whatever reason (even if it's just an added comment), then you sho= uld > +add braces. Otherwise, it would be too easy to insert a statement jus= t > +before that comment (without adding braces), thinking it is already a > +multi-statement loop: seems redundant with this paragraph. Besides, it makes for an awkward fl= ow: when omitting is good when it is bad example of good when it is bad example of bad Deleting the paragraph in question makes for a nicer flow, with no loss of information: when it is good example of good when it is bad example of bad --=20 Eric Blake eblake@redhat.com +1-801-349-2682 Libvirt virtualization library http://libvirt.org --------------enig6CF19E5285445A96AE7667E3 Content-Type: application/pgp-signature; name="signature.asc" Content-Description: OpenPGP digital signature Content-Disposition: attachment; filename="signature.asc" -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.10 (GNU/Linux) Comment: Public key at home.comcast.net/~ericblake/eblake.gpg Comment: Using GnuPG with Fedora - http://enigmail.mozdev.org/ iEYEARECAAYFAkvHHMwACgkQ84KuGfSFAYDfQwCggSuBWtsdbqkOB5NRr1erf3LM V5EAoI+StiJw/9G6fcMdd4vOvIU+MGs+ =hSYd -----END PGP SIGNATURE----- --------------enig6CF19E5285445A96AE7667E3-- From unknown Tue Jun 24 05:13:28 2025 X-Loop: help-debbugs@gnu.org Subject: bug#5951: [PATCH] doc: document our code formatting policy regarding curly braces Resent-From: Jim Meyering Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-To: owner@debbugs.gnu.org Resent-CC: bug-coreutils@gnu.org Resent-Date: Thu, 15 Apr 2010 17:01:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 5951 X-GNU-PR-Package: coreutils X-GNU-PR-Keywords: patch To: Eric Blake Cc: 5951@debbugs.gnu.org Received: via spool by 5951-submit@debbugs.gnu.org id=B5951.127135085019213 (code B ref 5951); Thu, 15 Apr 2010 17:01:02 +0000 Received: (at 5951) by debbugs.gnu.org; 15 Apr 2010 17:00:50 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1O2SQr-0004zq-VF for submit@debbugs.gnu.org; Thu, 15 Apr 2010 13:00:50 -0400 Received: from smtp2-g21.free.fr ([212.27.42.2]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1O2SQn-0004zl-V2 for 5951@debbugs.gnu.org; Thu, 15 Apr 2010 13:00:47 -0400 Received: from smtp2-g21.free.fr (localhost [127.0.0.1]) by smtp2-g21.free.fr (Postfix) with ESMTP id BACD54B01B0 for <5951@debbugs.gnu.org>; Thu, 15 Apr 2010 19:00:37 +0200 (CEST) Received: from mx.meyering.net (mx.meyering.net [82.230.74.64]) by smtp2-g21.free.fr (Postfix) with ESMTP id D60914B00F8 for <5951@debbugs.gnu.org>; Thu, 15 Apr 2010 19:00:34 +0200 (CEST) Received: by rho.meyering.net (Acme Bit-Twister, from userid 1000) id 784C7AEF; Thu, 15 Apr 2010 19:00:34 +0200 (CEST) From: Jim Meyering In-Reply-To: <4BC71CCA.3030907@redhat.com> (Eric Blake's message of "Thu, 15 Apr 2010 08:03:54 -0600") References: <87wrw9azvq.fsf@meyering.net> <4BC71CCA.3030907@redhat.com> Date: Thu, 15 Apr 2010 19:00:34 +0200 Message-ID: <877ho8abwt.fsf@meyering.net> Lines: 161 MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Spam-Score: -3.1 (---) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -3.1 (---) Eric Blake wrote: > On 04/15/2010 02:22 AM, Jim Meyering wrote: >> Hello, >> >> I was burned by a multi-line single-stmt (no braces) loop body >> in libvirt yesterday: >> >> http://thread.gmane.org/gmane.comp.emulators.libvirt/23715 >> >> and that has prompted me to write the following, >> which codifies my personal policy/practice. It may >> be derived from the GCS, but I haven't checked yet. >> >> Any suggestions or comments before I push? > > Looks good, except: > >> +Curly braces: use judiciously >> +============================= >> +Omit the curly braces around an "if", "while", "for" etc. body only when >> +that body occupies a single line. In every other case we require the braces. >> +This ensures that it is trivially easy to identify a single-*statement* loop: >> +each has only one *line* in its body. >> + >> +For example, do not omit the curly braces even when the body is just a >> +single-line statement but with a preceding comment. > > the paragraph above... Thanks. I removed those two lines and made this change below: -It seems safe not to require curly braces in this case, +It is safe not to require curly braces in code like this, since the further-indented second body line makes it obvious that this is still a single-statement body. >From f8291d0ec489c6363769c3c767b161ffbdb7f082 Mon Sep 17 00:00:00 2001 From: Jim Meyering Date: Thu, 15 Apr 2010 10:17:47 +0200 Subject: [PATCH] doc: document our code formatting policy regarding curly braces * HACKING (Curly braces: use judiciously): New section. --- HACKING | 101 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 101 insertions(+), 0 deletions(-) diff --git a/HACKING b/HACKING index 124c666..18e9c54 100644 --- a/HACKING +++ b/HACKING @@ -233,6 +233,107 @@ Try to make the summary line fit one of the following forms: maint: change-description +Curly braces: use judiciously +============================= +Omit the curly braces around an "if", "while", "for" etc. body only when +that body occupies a single line. In every other case we require the braces. +This ensures that it is trivially easy to identify a single-*statement* loop: +each has only one *line* in its body. + +Omitting braces with a single-line body is fine: + + while (expr) + single_line_stmt (); + +However, the moment your loop/if/else body extends onto a second line, +for whatever reason (even if it's just an added comment), then you should +add braces. Otherwise, it would be too easy to insert a statement just +before that comment (without adding braces), thinking it is already a +multi-statement loop: + + while (true) + /* comment... */ // BAD: multi-line body without braces + single_line_stmt (); + +Do this instead: + + while (true) + { /* Always put braces around a multi-line body. */ + /* explanation... */ + single_line_stmt (); + } + +There is one exception: when the second body line is not +at the same indentation level as the first body line. + + if (expr) + error (0, 0, _("a diagnostic that would make this line" + " extend past the 80-column limit")); + +It is safe not to require curly braces in code like this, +since the further-indented second body line makes it obvious +that this is still a single-statement body. + +To reiterate, don't do this: + + if (expr) + while (expr_2) // BAD: multi-line body without braces + { + ... + } + +Do this, instead: + + if (expr) + { + while (expr_2) + { + ... + } + } + +However, there is one exception in the other direction, when +even a one-line block should have braces. +That occurs when that one-line, brace-less block +is an "else" block, and the corresponding "then" block *does* use braces. +In that case, either put braces around the "else" block, or negate the +"if"-condition and swap the bodies, putting the one-line block first +and making the longer, multi-line block be the "else" block. + + if (expr) + { + ... + ... + } + else + x = y; // BAD: braceless "else" with braced "then" + +This is preferred, especially when the multi-line body is more +than a few lines long, because it is easier to read and grasp +the semantics of an if-then-else block when the simpler block +occurs first, rather than after the more involved block: + + if (!expr) + x = y; /* more readable */ + else + { + ... + ... + } + +If you'd rather not negate the condition, then add braces: + + if (expr) + { + ... + ... + } + else + { + x = y; + } + + Use SPACE-only indentation in all[*] files ========================================== We use space-only indentation in nearly all files. -- 1.7.1.rc1.248.gcefbb From unknown Tue Jun 24 05:13:28 2025 MIME-Version: 1.0 X-Mailer: MIME-tools 5.427 (Entity 5.427) X-Loop: help-debbugs@gnu.org From: help-debbugs@gnu.org (GNU bug Tracking System) To: Jim Meyering Subject: bug#5951 closed by Jim Meyering (Re: bug#5951: [PATCH] doc: document our code formatting policy regarding curly braces) Message-ID: References: <87ljcn7vuz.fsf@meyering.net> <87wrw9azvq.fsf@meyering.net> X-Gnu-PR-Message: they-closed 5951 X-Gnu-PR-Package: coreutils X-Gnu-PR-Keywords: patch Reply-To: 5951@debbugs.gnu.org Date: Fri, 16 Apr 2010 06:31:02 +0000 Content-Type: multipart/mixed; boundary="----------=_1271399462-12475-1" This is a multi-part message in MIME format... ------------=_1271399462-12475-1 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" This is an automatic notification regarding your bug report which was filed against the coreutils package: #5951: [PATCH] doc: document our code formatting policy regarding curly bra= ces It has been closed by Jim Meyering . Their explanation is attached below along with your original report. If this explanation is unsatisfactory and you have not received a better one in a separate message then please contact Jim Meyering by replying to this email. --=20 5951: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=3D5951 GNU Bug Tracking System Contact help-debbugs@gnu.org with problems ------------=_1271399462-12475-1 Content-Type: message/rfc822 Content-Disposition: inline Content-Transfer-Encoding: 7bit Received: (at 5951-done) by debbugs.gnu.org; 16 Apr 2010 06:30:26 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1O2f4L-0003Ex-4H for submit@debbugs.gnu.org; Fri, 16 Apr 2010 02:30:25 -0400 Received: from smtp3-g21.free.fr ([212.27.42.3]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1O2f4I-0003Ep-4X for 5951-done@debbugs.gnu.org; Fri, 16 Apr 2010 02:30:23 -0400 Received: from smtp3-g21.free.fr (localhost [127.0.0.1]) by smtp3-g21.free.fr (Postfix) with ESMTP id CA66A81812A for <5951-done@debbugs.gnu.org>; Fri, 16 Apr 2010 08:30:15 +0200 (CEST) Received: from mx.meyering.net (mx.meyering.net [82.230.74.64]) by smtp3-g21.free.fr (Postfix) with ESMTP id D0CF0818062 for <5951-done@debbugs.gnu.org>; Fri, 16 Apr 2010 08:30:12 +0200 (CEST) Received: by rho.meyering.net (Acme Bit-Twister, from userid 1000) id ACDE1AEE; Fri, 16 Apr 2010 08:30:12 +0200 (CEST) From: Jim Meyering To: Eric Blake Subject: Re: bug#5951: [PATCH] doc: document our code formatting policy regarding curly braces In-Reply-To: <877ho8abwt.fsf@meyering.net> (Jim Meyering's message of "Thu, 15 Apr 2010 19:00:34 +0200") References: <87wrw9azvq.fsf@meyering.net> <4BC71CCA.3030907@redhat.com> <877ho8abwt.fsf@meyering.net> Date: Fri, 16 Apr 2010 08:30:12 +0200 Message-ID: <87ljcn7vuz.fsf@meyering.net> Lines: 87 MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Spam-Score: -3.1 (---) X-Debbugs-Envelope-To: 5951-done Cc: 5951-done@debbugs.gnu.org X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -3.1 (---) ... > Thanks. I removed those two lines and made this change below: > > -It seems safe not to require curly braces in this case, > +It is safe not to require curly braces in code like this, > since the further-indented second body line makes it obvious > that this is still a single-statement body. One more tweak: (only the first hunk has a wording change. The others are just re-flowed. ) >From 36cc6ac787d3c8f98c88cfe14c42fe27027b785b Mon Sep 17 00:00:00 2001 From: Jim Meyering Date: Fri, 16 Apr 2010 08:21:32 +0200 Subject: [PATCH] doc: tweak HACKING * HACKING (Curly braces): Tweak a sentence. Filter a few paragraphs through "fmt". --- HACKING | 32 ++++++++++++++++---------------- 1 files changed, 16 insertions(+), 16 deletions(-) diff --git a/HACKING b/HACKING index 18e9c54..a6589d3 100644 --- a/HACKING +++ b/HACKING @@ -263,16 +263,16 @@ Do this instead: single_line_stmt (); } -There is one exception: when the second body line is not -at the same indentation level as the first body line. +There is one exception: when the second body line is not at the same +indentation level as the first body line. if (expr) error (0, 0, _("a diagnostic that would make this line" " extend past the 80-column limit")); -It is safe not to require curly braces in code like this, -since the further-indented second body line makes it obvious -that this is still a single-statement body. +It is safe to omit the braces in the code above, since the +further-indented second body line makes it obvious that this is still +a single-statement body. To reiterate, don't do this: @@ -292,13 +292,13 @@ Do this, instead: } } -However, there is one exception in the other direction, when -even a one-line block should have braces. -That occurs when that one-line, brace-less block -is an "else" block, and the corresponding "then" block *does* use braces. -In that case, either put braces around the "else" block, or negate the -"if"-condition and swap the bodies, putting the one-line block first -and making the longer, multi-line block be the "else" block. +However, there is one exception in the other direction, when even a +one-line block should have braces. That occurs when that one-line, +brace-less block is an "else" block, and the corresponding "then" block +*does* use braces. In that case, either put braces around the "else" +block, or negate the "if"-condition and swap the bodies, putting the +one-line block first and making the longer, multi-line block be the +"else" block. if (expr) { @@ -308,10 +308,10 @@ and making the longer, multi-line block be the "else" block. else x = y; // BAD: braceless "else" with braced "then" -This is preferred, especially when the multi-line body is more -than a few lines long, because it is easier to read and grasp -the semantics of an if-then-else block when the simpler block -occurs first, rather than after the more involved block: +This is preferred, especially when the multi-line body is more than a +few lines long, because it is easier to read and grasp the semantics of +an if-then-else block when the simpler block occurs first, rather than +after the more involved block: if (!expr) x = y; /* more readable */ -- 1.7.1.rc1.269.ga27c7 ------------=_1271399462-12475-1 Content-Type: message/rfc822 Content-Disposition: inline Content-Transfer-Encoding: 7bit Received: (at submit) by debbugs.gnu.org; 15 Apr 2010 08:23:12 +0000 Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1O2KLw-0000o5-Ah for submit@debbugs.gnu.org; Thu, 15 Apr 2010 04:23:12 -0400 Received: from mx10.gnu.org ([199.232.76.166]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1O2KLs-0000nz-Le for submit@debbugs.gnu.org; Thu, 15 Apr 2010 04:23:09 -0400 Received: from lists.gnu.org ([199.232.76.165]:60709) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1O2KLp-0004Aw-Jd for submit@debbugs.gnu.org; Thu, 15 Apr 2010 04:23:05 -0400 Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1O2KLo-0006ex-T8 for bug-coreutils@gnu.org; Thu, 15 Apr 2010 04:23:04 -0400 Received: from [140.186.70.92] (port=35571 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1O2KLj-0006el-Pj for bug-coreutils@gnu.org; Thu, 15 Apr 2010 04:23:04 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.0 (2010-01-18) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-1.9 required=5.0 tests=BAYES_00,RCVD_IN_DNSWL_NONE autolearn=unavailable version=3.3.0 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1O2KLh-00023g-OZ for bug-coreutils@gnu.org; Thu, 15 Apr 2010 04:22:59 -0400 Received: from smtp3-g21.free.fr ([212.27.42.3]:56997) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1O2KLh-000239-5L for bug-coreutils@gnu.org; Thu, 15 Apr 2010 04:22:57 -0400 Received: from smtp3-g21.free.fr (localhost [127.0.0.1]) by smtp3-g21.free.fr (Postfix) with ESMTP id 63B19818047 for ; Thu, 15 Apr 2010 10:22:51 +0200 (CEST) Received: from mx.meyering.net (mx.meyering.net [82.230.74.64]) by smtp3-g21.free.fr (Postfix) with ESMTP id 764208181AB for ; Thu, 15 Apr 2010 10:22:49 +0200 (CEST) Received: by rho.meyering.net (Acme Bit-Twister, from userid 1000) id 311DDC46; Thu, 15 Apr 2010 10:22:49 +0200 (CEST) From: Jim Meyering To: bug-coreutils@gnu.org Subject: [PATCH] doc: document our code formatting policy regarding curly braces Date: Thu, 15 Apr 2010 10:22:49 +0200 Message-ID: <87wrw9azvq.fsf@meyering.net> Lines: 140 MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) X-detected-operating-system: by monty-python.gnu.org: GNU/Linux 2.6, seldom 2.4 (older, 4) X-Spam-Score: -3.8 (---) X-Debbugs-Envelope-To: submit X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: debbugs-submit-bounces@debbugs.gnu.org Errors-To: debbugs-submit-bounces@debbugs.gnu.org X-Spam-Score: -5.1 (-----) Hello, I was burned by a multi-line single-stmt (no braces) loop body in libvirt yesterday: http://thread.gmane.org/gmane.comp.emulators.libvirt/23715 and that has prompted me to write the following, which codifies my personal policy/practice. It may be derived from the GCS, but I haven't checked yet. Any suggestions or comments before I push? >From a7d51ecb8ea2788081a23f1dce4eb0d503c02ce4 Mon Sep 17 00:00:00 2001 From: Jim Meyering Date: Thu, 15 Apr 2010 10:17:47 +0200 Subject: [PATCH] doc: document our code formatting policy regarding curly braces * HACKING (Curly braces: use judiciously): New section. --- HACKING | 104 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 104 insertions(+), 0 deletions(-) diff --git a/HACKING b/HACKING index 124c666..7ccd2be 100644 --- a/HACKING +++ b/HACKING @@ -233,6 +233,110 @@ Try to make the summary line fit one of the following forms: maint: change-description +Curly braces: use judiciously +============================= +Omit the curly braces around an "if", "while", "for" etc. body only when +that body occupies a single line. In every other case we require the braces. +This ensures that it is trivially easy to identify a single-*statement* loop: +each has only one *line* in its body. + +For example, do not omit the curly braces even when the body is just a +single-line statement but with a preceding comment. + +Omitting braces with a single-line body is fine: + + while (expr) + single_line_stmt (); + +However, the moment your loop/if/else body extends onto a second line, +for whatever reason (even if it's just an added comment), then you should +add braces. Otherwise, it would be too easy to insert a statement just +before that comment (without adding braces), thinking it is already a +multi-statement loop: + + while (true) + /* comment... */ // BAD: multi-line body without braces + single_line_stmt (); + +Do this instead: + + while (true) + { /* Always put braces around a multi-line body. */ + /* explanation... */ + single_line_stmt (); + } + +There is one exception: when the second body line is not +at the same indentation level as the first body line. + + if (expr) + error (0, 0, _("a diagnostic that would make this line" + " extend past the 80-column limit")); + +It seems safe not to require curly braces in this case, +since the further-indented second body line makes it obvious +that this is still a single-statement body. + +To reiterate, don't do this: + + if (expr) + while (expr_2) // BAD: multi-line body without braces + { + ... + } + +Do this, instead: + + if (expr) + { + while (expr_2) + { + ... + } + } + +However, there is one exception in the other direction, when +even a one-line block should have braces. +That occurs when that one-line, brace-less block +is an "else" block, and the corresponding "then" block *does* use braces. +In that case, either put braces around the "else" block, or negate the +"if"-condition and swap the bodies, putting the one-line block first +and making the longer, multi-line block be the "else" block. + + if (expr) + { + ... + ... + } + else + x = y; // BAD: braceless "else" with braced "then" + +This is preferred, especially when the multi-line body is more +than a few lines long, because it is easier to read and grasp +the semantics of an if-then-else block when the simpler block +occurs first, rather than after the more involved block: + + if (!expr) + x = y; /* more readable */ + else + { + ... + ... + } + +If you'd rather not negate the condition, then add braces: + + if (expr) + { + ... + ... + } + else + { + x = y; + } + + Use SPACE-only indentation in all[*] files ========================================== We use space-only indentation in nearly all files. -- 1.7.1.rc1.248.gcefbb ------------=_1271399462-12475-1--