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

[Mike Kaufman <mkaufman@xxxxxxxxxxxxxx>]

On Wed, Nov 28, 2001 at 12:09:48PM -0500, 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...

I can't comment on most of the stuff below, but I would advocate all
functions continue to have a header such as:

/******************************************
 this function does ...
 ... more on what it does ...
******************************************/
void this_function(blah){

}

There are only a couple places in the code that don't do this already.
I have found this _extremely_ helpful in browsing through the code.
The solid line of *** catches the eye very easily and separates the
functions effectively. Now if only all the functions' functions were
well documented...you see too much of:

/******************************************
 ... <-- that's really there
******************************************/

for the same reasons (eye-catchingness), I prefer multline
intra-function comments to look like:

  int x;

  /* we're doing this ...  */
  /* and if that's not     */
  /* enough we'll do foo() */

  foo()

but then again, that's pretty anal...

-mike

PS: so maybe, before anybody does anymore voting, people should post
their pet coding styles (that they think are important enough to foist
on everybody else), set a deadline for this, so we don't have to vote
for three different sets of lists, and then vote. So these above I would
put as 10d and the new section on function header comments.

example coding-style-idea deadline: Sunday Dec 2, 1200 GMT 

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