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 <jan dot kratochvil at redhat dot com>]

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