Complete.Org: Mailing Lists: Archives: freeciv-dev: November 2001:
[Freeciv-Dev] Re: Coding Guideline --- more variants

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

[Top] [All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index] [Thread Index]
To: freeciv development list <freeciv-dev@xxxxxxxxxxx>
Subject: [Freeciv-Dev] Re: Coding Guideline --- more variants
From: Mike Kaufman <mkaufman@xxxxxxxxxxxxxx>
Date: Wed, 28 Nov 2001 16:08:34 -0600

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 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() */


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


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

[Prev in Thread] Current Thread [Next in Thread]