Re: [doc patch] gdbint: braces for two lines in code [Re: [patch] Fix for PR gdb/9538 (loading of separate debuginfo and symlinks).]

Jan Kratochvil
2012-01-13T11:06:50Z

On Fri, 13 Jan 2012 04:46:02 +0100, Joel Brobecker wrote:
> My 2 cents: I think it's too trivial to object... I do not think
> there are any solid argument in favor of one or the other. A decision
> has been made, let's go with it.

I was posting the patch more for its language + understandability part.

On Fri, 13 Jan 2012 09:08:04 +0100, Eli Zaretskii wrote:
> > +@smallexample
> > +if (i)
> > + @{
> > + /* Return success. */
> > + return 0;
> > + @}
> > +@end smallexample
>
> If you really want to make a point that this rule is valid even if the
> second line is a comment, then I suggest to say so explicitly in the
> text.

Two non-comment statements really require a block. It would not work
otherwise. The poi

> Otherwise, I'd suggest to replace the comment with a non-comment line.

The point was the braces should be there even if it is a comment line. This
has no compiler justification, it is just the coding style.

OK this way?

It also addresses:

ok:
if (i)
{
/* Here is no operation needed and even if the comment is a single
statement braces would be better. */
}

not ok:
if (i)
/* Here is no operation needed and even if the comment is a single
statement braces would be better. */;

This mail became a real nitpick/bikeshed.

Thanks,
Jan

gdb/doc/
2012-01-13 Jan Kratochvil <jan.kratochvil@redhat.com>

* gdbint.texinfo (Coding Standards): Require braces for two lines of
code.

--- a/gdb/doc/gdbint.texinfo
+++ b/gdb/doc/gdbint.texinfo
@@ -5849,6 +5849,27 @@ the following guidelines:
@tab (pointer dereference)
@end multitable

+Any two or more lines in code should be wrapped in braces even if one of
+them is a comment line. The readability is improved as such two lines look
+as separate code lines which would require the braces for compiler. Use:
+
+@smallexample
+if (i)
+ @{
+ /* Return success. */
+ return 0;
+ @}
+@end smallexample
+
+@noindent
+and not:
+
+@smallexample
+if (i)
+ /* Return success. */
+ return 0;
+@end smallexample
+
@subsection Comments

@cindex comment formatting