[Freeciv-Dev] Re: Coding Guideline --- more variants

[Andrew Sutton <ansutton@xxxxxxx>]

On Wednesday 28 November 2001 12:01 pm, Petr Baudis wrote:
> Hmm, OTOH there are people actually waiting for the guideline to be
> finished (e.g. me ;), so don't run it MUCH longer :-).

agreed...

> > for ALL externally used functions and structures (i.e. everything that
> > gets called or passed) shouuld be commented using /** */. e.g.
>
> That looks ugly. The reason for exactly this style? Actual
> /***...*\n*\n***...*/ seems nicer to me.  Well, it would be nice to be able
> to distinguish local and external symbols, however maybe /**[X]**...\n...
> would do better job, wouldn't it?

actually, there is a reason. a very, very, good reason. it's the javadoc 
format. it allows programs like doxygen to parse thru the code and generate 
external documentation based on the comments provided within that comment 
block. doxygen, for example, will generate a nice set of web pages containing 
all the documentation provided and link stuff together. it's an extremely 
powerful tool.

adopting this commenting style will eliminate the need for an internals guide 
and allow new developers to jump in to development alot faster without having 
to go thru all the code hand by hand in order to figure out what they need to 
change or patch or whatever.

besides, after you get use to it it kind of takes on a grace all its own ;) 
and you can't beat a nicely cross-referenced web page containing all your 
project documentation - especially when you don't have to maintain it.

andy