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

[Mike Kaufman <kaufman@xxxxxxxxxxxxxxxxxxxxxx>]

On Thu, Feb 21, 2002 at 11:30:37PM +0100, Petr Baudis wrote:
> I already had some discussion with Mike about this - he wants variables
> descriptions like:
> 
> char *foo; /* bar bar bar bar bar ... barbar
>           * barbarbar bar bar */
> 
> but I want it like:
> 
> /* bar bar bar bar bar ... barbar
>  * barbarbar bar bar */
> char *foo;
> 
> The first one MAY (I think it does the contrary ;) improve reading of
> declarations, but its leaks are enlarging together with comment's length. I
> find the second one as more convient to read (especially with syntax
> highlighting, which any sane editor should do, but w/o it as well) and I

This is a slightly subjective discussion, but then I suppose style is...

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;

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 */

  /* holy bar! */
  foo = bar * bar - total_power;
  foobar = belligerence->no;

it seems to me entirely obvious which is more readable, i.e. this is how it
should be.

> already used this in my previous patches and I saw others starting to use this
> too (can't actually remember who exactly, though ;).

Neither of these is an argument for. This just means that I need to stop the
"precedent" here.

-mike

> So I decided to hear your opinions about this issue - I particulary care about
> opinions of Greg, Raahul, Ross (altough I doubt he'll notice this ;) and
> Raimar, but others are welcome too :).
> 
> PS: sorry for briefness of this mail but it's relatively late for me today, 
> but
> I wanted this mail to get out today yet.
> 
> -- 
> 
>                               Petr "Pasky" Baudis
> 
> * elinks maintainer                * IPv6 guy (XS26 co-coordinator)
> * IRCnet operator                  * FreeCiv AI hacker
> .
> No one can feel as helpless as the owner of a sick goldfish.
> .
> Public PGP key && geekcode && homepage: http://pasky.ji.cz/~pasky/