[Freeciv-Dev] Function comments.

[Gregory Berkolaiko <Gregory.Berkolaiko@xxxxxxxxxxxx>]

We should strive to put an explanatary comment before each function, 
however obvious it might seem at the moment of it's creation.

Ideally we will not have any 
/***************************
...
***************************/
left.

I also suggest we put it in the coding style guide.


On Sat, 28 Sep 2002, Mike Kaufman wrote:

> On Sat, Sep 28, 2002 at 10:19:06AM -0500, Mike Kaufman wrote:
> > On Sat, Sep 28, 2002 at 08:05:55AM -0700, Per I. Mathisen wrote:
> > > On Fri, 27 Sep 2002, Jason Short wrote:
> > > > The problem is Sun CC, at least, doesn't support variadic macros
> > > > (variable options in macros).For freelog there's an "#ifdef __GNUC__"
> > > > check, with a static function declared in the header for other 
> > > > compilers.
> > > 
> > > > As I understand it, the reason it's important to have this code be
> > > > macros/inlined is that there are a LOT of freelog calls throughout the
> > > > code, and most of them can be optimized away
> > > 
> > > The problem itself can be optimized away. Since all developers use gcc,
> > > and only developers watch these log messages, we can add gcc to the list
> > > of development tools that are needed to program for freeciv, and #ifdef
> > > __GNUC__ the macros. You will need the rest of the GNU toolchain
> > > (automake, autoconf, gettext, etc) in order to build from cvs anyway.
> > 
> > hmm. at least for the immediate, I don't think we're saving ourselves much,
> > since these macros all call a bunch of functions themselves. An extra hop
> > isn't really going to mean much. I suggest an ailog.c and make these macros
> > functions.
> > 
> > BTW: we should be using my_snprintf instead of sprintf in those routines.
> 
> and a patch to do this.
> it also runs slightly faster than the CVS version.
> 
> -mike
>