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

[Daniel Sjölie <deepone@xxxxxxxxxx>]

On 2001-11-28 12:09:48, Andrew Sutton wrote:
> 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.

I second this... Doxygen is a Good Thing(tm)

/Daniel

-- 
Now take a deep breath, smile and don't take life so seriously... :)