MALLOC problem

[Nick Keighley]

Depends. In my opinion, it's good practice to document every argument as
well as the return value of a function IFF this function is part of a
public API. Also add exceptions for languages that have them.

And, of course, it should be done in a standard format that allows for
automatic generation of API documentation (e.g. visual-studio XML
comments, javadoc or doxygen).

yuk

 

[Nick Keighley]

If you have to, you have to. However, as others have mentioned, there is
no sense in adding comments that say the same thing as the code, like
for instance

/* output the contents of the array */
prn_array(array, size);

Do you think the above comment makes the statement easier to understand?

yes. But only because I don't find "prn" immediatly obvious. Come back
FORTRAN all is forgiven!

 

[Felix Palmen]

yuk

If you have some arguments against my opinion, please share them.
Otherwise just keep your mouth shut.

 

[David Resnick]

yuk

Really? Yuk? I think over-commenting is bad too, but using a
consistent format like javadoc and documenting all functions and
variables in a *PUBLIC API* sounds good to me too. We do that where I
work in the header files, and it is quite helpful. Yes it is an issue
keeping the comments in sync with the usage. Code reviews should
catch that you'd hope -- at least when I review I look carefully at
the comments as well.

I guess I'd rather count on good comments than on someones notion of
what is obvious in terms of variable names and function names. Yes,
in some ideal world the names are so good and the code so clear and
the maintainer (who isn't usually the writer) has the same language
and domain knowledge and assumptions as the writer. But for the rest
of the time it is nice to have some hints, even if sometimes
redundant. And at least the comments are in the code, unlike say the
design document (if there even is one) which tends to get MORE out of
sync with the code unless one is quite careful.

All IMHO of course, and there is a happy medium. Too many comments,
and truly inane comments, makes the code harder to digest as well.

-David

 

[Nick Keighley]

* Nick Keighley <[email protected]>:

context reinserted:-
***
Depends. In my opinion, it's good practice to document every argument
as

well as the return value of a function IFF this function is part of a
public API. Also add exceptions for languages that have them.

And, of course, it should be done in a standard format that allows for
automatic generation of API documentation (e.g. visual-studio XML
comments, javadoc or doxygen). ***


If you have some arguments against my opinion, please share them.

I've never found automatically generated documentaion to be very
useful. Why not read the code? Or at least the header file? Perhaps
such things are more useful with publically available stuff.

Otherwise just keep your mouth shut.

I reserve the right to open my mouth whenever I feel like it.

 

[Felix Palmen]

I've never found automatically generated documentaion to be very
useful. Why not read the code? Or at least the header file? Perhaps
such things are more useful with publically available stuff.

That's exactly what I was talking about: "IFF the function is part of a
public API". I don't think anybody likes scanning some header files in
order to figure out how to use an API. In other words: Documenting any
function with its arguments etc is very useful for those function
intended to be called by "external" users.

I reserve the right to open my mouth whenever I feel like it.

And I reserve the right to stop reading anybody just posting some rude
single-worded disagreement with no justification at all, but
fortunately, you stopped doing that.

Regards,
Felix