On Sat, 2002-11-23 at 05:54, Christian Stimming wrote: > Agreed too. If somebody asks, I'd vote for doxygen. >
Doxygen looks good to me, and probably can generate a wider range of
output than javadoc. I know there's other stuff out there, but if
everyone agrees, why don't we standardize on doxygen? Silence is
concurrence...
> > > I really like Benoit's suggestion of moving documentation to
> > > header/source comments, because it's much more likely to be kept
> > > up-to-date there, than if it were a separately maintained entity.
> >
> > Source please, not header. I know there are currently lots of comments
> > in header files, but I prefer comments closer to the actual code and I
> > think the are more likely to be updated there. How much of your time do
> > you spend editing .c files vs. .h files?
>
> Header please, not source.
>
> Seriously, if my parts of the code are using functions from somewhere else,
> then my code sees only the header files and so do I. The header file is the
> place where the declaration takes place, and ideally the comment in front of
> that declaration should give me absolutely enough knowledge to understand
> what that particular function is going to do. Contrary to that, a header file
> with undocumented declarations is pretty much useless for any human reader.
> Note that we have two different questions here: On the one hand, the comments
> should be in a place where the user/reader easily finds them. Which would be
> in the header. On the other hand, the comments should always be kept up to
> date by the developer. Which does happen or not happen pretty much regardless
> of whether the comments are placed in the header or the source -- developers
> can forget it in both places, or can remember that in both places. Therefore
> I would definitely vote for function documentation in the header.
Would it hurt to have it in both places? That would be more to
maintain. I tend to agree about having it in the header, unless the C
source doesn't have a matching header. I really understand both
points--when you're working on a source file, it's more convenient to
have the comments there. OTOH, when you are coming into a system, you
tend to look at the headers. There's probably not a perfect solution,
and it may depend on how well doxygen can weed out duplicate comments,
but I vote for putting official comments (i.e., API reference stuff) in
the header, and less formal comments in the source. The API reference
is less likely to change on a day-to-day basis.
re coding style, how's this:
/**
* Some constructive commentary
* Beer is good...
*/
type *function(const char* arg)
{
if () {
something;
} else {
something else;
}
for (x; y; z) {
do {
something;
} while (stuff)
}
switch (var) {
case Y:
have a ball;
break; /* a glass */
default:
get a ride;
}
}
I like 4 spaces for indents (wish I was ambitious enough to make Vi
indent w/4 spaces instead of a tab...). 4 spaces creates enough
indentation to make reading easier. OTOH (and this is a matter of
coding practice more than style), if you have too many nested
statements, the lower level nesting should be relegated to a new
function. The less lines-per-function the better, IMO. Keeping that in
mind, I like the above example.
I have seen flamefests about this type of thing before, and it's really
not as important as all that--it just helps make the code easier to read
when you have a standard and published style utilized across all the
code.
ciao,
--
Matthew Vanecek
perl -e 'print $i=pack(c5,(41*2),sqrt(7056),(unpack(c,H)-2),oct(115),10);'
********************************************************************************
For 93 million miles, there is nothing between the sun and my shadow except me.
I'm always getting in the way of something...
signature_asc_DEFANGED-35654.DEFANGED-80912
Description: application/defanged-80912
