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

[Raahul Kumar <raahul_da_man@xxxxxxxxx>]

--- Mike Kaufman <kaufman@xxxxxxxxxxxxxxxxxxxxxx> wrote:
> 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:
> > 
> >  Style One:
> > char *foo; /* bar bar bar bar bar ... barbar
> >         * barbarbar bar bar */
> > 
> > but I want it like:
> > 
> > Style Two
> > /* bar bar bar bar bar ... barbar
> >  * barbarbar bar bar */
> > char *foo;
> > 

I find the current code is like mostly like Style one above. I personally
prefer
to have one line comments like

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

For multi-line comments I prefer Style two. I feel another round of voting
on round 2 of the style guide coming on.

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

That happens a lot in the AI code. I find it hard too. Too many one line or two
line comments together is very hard to read.

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

You dared to doubt me. The pitchforks and torches are out, the mob is not
going home without blood tonight.

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


__________________________________________________
Do You Yahoo!?
Yahoo! Sports - Coverage of the 2002 Olympic Games
http://sports.yahoo.com