To restate the question: Which is better, one central detailed comment, or several smaller "sprinkles"?
Bear with me while I set up the scene:
I've got this function for popping a value from a queue implementation:
int queue_pop(queue *list, void **pValue);
If you're familiar with C, you understand that calling this function like this:
struct foo *pFoo; int rc; rc = queue_pop(g_FooList, &pFoo);
you get this:
gcc: warning-incompatible pointer type passing 'foo **' to parameter of type 'void **'
Now, as it happens, calling this function like this is perfectly safe; the function never addresses the dereferenced pointer as anything other than a void*, and memory allocation and copying is done based strictly on the element size, which is defined on any given queue. But, to avoid the warnings, I call it like this:
rc = queue_pop(g_FooList, (void**)&pFoo);
which is also not strictly portable in C, but again, in this case, is perfectly safe. But, since casting function arguments is almost NEVER necessary in C, and is in fact almost ALWAYS covering up an error, I document the first call of this type in every function like this:
/* Explicit cast - see comments on queue_pop function in queue.c */ rc = queue_pop(g_FooList, (void**)&pFoo);
That way, anyone reading the code can open the queue.c file and read a detailed explanation of why this is OK, and not to worry about it. And, since they won't do that, at least they know that it was done on purpose, and there is a reason.
The question arises because somone suggested that I get rid of the cast -- since it is so unusual -- and just call the function with the concrete pointer type. Then suppress the warning with a
#pragma push at the top of the source file, and put a detailed comment on the pragma explaining the suppression. Since the codebase is eventually going to be open-source, and the source code comments (versus header file comments) are therefore going to have a wider audience than normal, it's more organized that way.
Aside from the fact that I'm not a big fan of suppressing warnings in the first place (except for some of the sillier MSVC ones), it's been my exprerience that:
- A) people will not read
- B) if you want someone to read something, you better stick it right in front of their eyeballs
- C) see A
comments tag says it's for questions about "Best Practices", but I realize this one might tend a bit too far toward "opiniony". If that's the case, just hang a few downvotes on it, and I'll delete the question.
EDIT I saw this question, but it looks like a general mosh about whether or not to use comments at all. That's not the issue here: I'm definitely going to use some kind of comment.