[Freeciv-Dev] [POLL] Variables descriptions: Votes on Style

[Raahul Kumar <raahul_da_man@xxxxxxxxx>]

--- Daniel L Speyer <dspeyer@xxxxxxxxxxx> wrote:
> On Fri, 22 Feb 2002, Raahul Kumar wrote:
> 
> > 
> > --- 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.
> > 
> 
> I would have to go with style 1, except on excessively long
> comments.  Style two should be usable for section headers:
> 

Greg, do you want to count the votes again on the style guide?

> void foo(){
>   /* Gui-building */
>   GtkWidget *foo, *foo2, *foo3;
>   GList *l; /* Needed for bar */
>   /* file-mangling */
>   int fd[256]; /* Apologies, explanations, arguments as to
>                 * why this won't crash the program... */
>   FILE *qux;
>     .
>     .
>     .
> }
> 
> Now, if Style 2 is used, the headers would have to be like
> /*************************Gui-building**********************/
> which would really be obnoxious and disruptive.
> 
> OTOH, if the number of lines for style 2 is three less than style one, it
> should probably be used, though putting the variable declaration on its
> own line would be better.
> 
> My US$.02
> 
> --Daniel Speyer
> If you *don't* consider sharing information to be morally equivalent to 
> kidnapping and murder on the high seas, you probably shouldn't use the
> phrase "software piracy."
> 
> > > > 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
> > 
> > 
> 
> 


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