bug#5951: [PATCH] doc: document our code formatting policy regarding curly braces

[Eric Blake]

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...

> +
> +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:

seems redundant with this paragraph.  Besides, it makes for an awkward flow:

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

-- 
Eric Blake   address@hidden    +1-801-349-2682
Libvirt virtualization library http://libvirt.org

signature.asc
Description: OpenPGP digital signature