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

[Daniel L Speyer <dspeyer@xxxxxxxxxxx>]

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:

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