[Freeciv-Dev] Re: [POLL] Variables descriptions

[Reinier Post <rp@xxxxxxxxxx>]

On Thu, Feb 21, 2002 at 05:00:46PM -0600, Mike Kaufman wrote:

> For me, and most likely, for other people, when I'm reading down fresh
> code, this is _not_ hard for me to parse:
> 
>   /* bar bar bar bar bar ... barbar
>    * barbarbar bar bar */
>   char *foo;
> 
> this however, _is_ hard:
> 
>   /* bar bar bar bar bar ... barbar
>    * barbarbar bar bar bar bar bar */
>   char *foo = bar * bar - total_power;
>   /* bar bar bar bar bar ... barbar
>    * barbarbar this is hard for me to parse */
>   char *foobar = belligerence->no;
>   /* bar bar bar bar bar ... barbar
>    * barbarbar bar bar peew */
>   char *foo_really = 0;

Yes.  I would precede the comments with empty lines.
> 
> because everything runs together.
> when varables _must_ have lengthy comments, I would prefer:
> 
>   char *foo;            /* bar bar bar bar bar ... barbar
>                          * barbarbar bar bar bar bar bar */
>   char *foobar;         /* more blah blah 
>                          * barbarbar bar bar */
>   char *foo_really = 0; /* bar bar bar bar bar ... barbar
>                          * barbarbar bar bar peew */

I tend to use

  char *foo;
    /* bar bar bar bar bar ... barbar
      barbarbar bar bar bar bar bar */

The indentation and sometimes newline make it obvious the comment
belongs to the previous statement.  Comments pertaining to multiple
statements precede them, comments pertaining to a single statement
are treated like this.  But this is just what I happen to do.

-- 
Reinier