[Freeciv-Dev] Re: AI cleanup Version 3

[Petr Baudis <pasky@xxxxxxxxxxx>]

Dear diary, on Sat, Jan 05, 2002 at 11:21:15PM CET, I got a letter, where
Raimar Falke <hawk@xxxxxxxxxxxxxxxxxxxxxxx> told me, that...  ..snip
attributions and superfluous parts of conversation.. ;)
> > > > > > > +  int a=0, b, min_turns_to_dest, d, e, move_rate, n, v, i, f,
> > > > > > > a0, b0, ab, g;
> > > > > > min_turns_to_dest seems too long for me - what about 'delay'? ;)
> > > > > 
> > > > > This is a bit funny. One char names are too short and 17 char names
> > > > > are too long. Hell he didn't wrote minimal_turns_to_reach_destination
> > > > > like I would have done ;).
> > > > Well, if there is equally appropriate short name, why should we use the
> > > > long one? ;p
> > > 
> > > Because is was quite hard to decipher the AI code. I just don't want to
> > > loose the knowledge the people have gained in the last month again.
> > Well, if there is a doubt about the mean of the variable, there should be a
> > comment near its declaration. The variable name should just represent its
> > content, not explain it, IMHO.
> 
> So what would you prefer:
> 
> int d;
> int d; /* minimal number of turns to reach the destination (dest_x,dest_y) */
no way
> int delay;
comment will help
> int delay; /* minimal number of turns to reach the destination 
> (dest_x,dest_y) */
yes! :)
> int t;
> int t; /* minimal number of turns to reach the destination (dest_x,dest_y) */
no way
> int turns;
> int turns; /* minimal number of turns to reach the destination 
> (dest_x,dest_y) */
too little descriptive ;)
> * int min_turns_to_dest;
> int min_turns_to_dest; /* minimal number of turns to reach the destination 
> (dest_x,dest_y) */
too long
> int minimal_turns_to_reach_destination;
> int minimal_turns_to_reach_destination; /* minimal number of turns to reach 
> the destination (dest_x,dest_y) */
> 
> I like * best. You have the unit (turns) and also a short description of what
> is measured. And you don't have to provide a comment.
it's clear it will be in turns and not in seconds ;p. and what is measured is
minimal _delay_ before we will get to destination - and if you will once glance
to the declaration and comment, you will know what it means for the rest of your
examination of the function and you will be able to easily reference to it. I
just happen to think that a lot of long variables makes the code (especially
formulas) harder to read and should be avoided, if reasonable (if there's just
no short happy name, then ok_use_long_variable).

> There was a person (sorry no name available) which wanted that every local
> variable has a comment on it (like above).
If you will look at my patches, you will see I do it (almost everytime).

-- 

                                Petr "Pasky" Baudis

UN*X programmer, UN*X administrator, hobbies = IPv6, IRC, FreeCiv, (e)links
.
The advantage of GUI is that you can see everything you can change.
The disadvantage of GUI is that you can change only what you can see.
.
Public PGP key, geekcode and stuff: http://pasky.ji.cz/~pasky/