Re: [RFC] Bug zapper? :)
From: John Richard Moser
Date: Tue Aug 10 2004 - 10:22:41 EST
Jakob Oestergaard wrote:
On Mon, Aug 09, 2004 at 07:09:55PM -0400, John Richard Moser wrote:
...
Now, we could try another approach at this, below.
/* get_food(char **a)
* Gets the current food.
*
* INPUT:
* - char **a
* Pointer to a pointer for the outputted food.
* OUTPUT:
* - Return
* none.
* - *a
* Set to a copy of the current food.
* PROCESS:
* - Set '*a' to a newly allocated block of memory containing a copy
* of the current food (global_food)
* STATE CHANGE:
* none.
*/
...
There's just more to it than this.
Even in the almost "self explanatory" example you gave, even with your
suggested style of commenting, there are still problems:
Your comments do not describe who's responsible for allocating/freeing
which memory areas the various pointers point at.
Then my comment above is bad. Should add that it frees the old block.
Your get_food() function will cause a write at address 0 if malloc()
fails.
My code is bad probably. I should return if malloc() fails.
So, you have provided some good examples that no particular commenting
style is going to solve the common problems that all larger C software
projects face to some extent (memory management and error handling).
Memory managment is annoying. I'm working on a reference counting
scheme on the side; but that's a fair bit of overhead. I've never been
able to argue that reference counting is less overhead than manual mm;
but I've also never been able to argue that trying to guess if you can
free memory based on your program's internal state is less overhead than
reference counting.
There's places where this is inappropriate, and places where it's
appropriate. Inside the kernel, though, I can't imagine where it'd be
appropriate. . . . yeh this is a bad idea, isn't it? :p
...
These comment blocks are *MUCH* more verbose.
Agreed :)
They describe the process
loosely, but do give enough information to allow understanding without
questions.
That's where I disagree.
They do provide an illusion of knowledge though (for example, you did
not mention the built-in segfault mechanism, that was a hidden feature).
The function isn't made to segfault; segfaulting is what happens when
you screw up your code. :)
I guess it should describe INPUT, OUTPUT, PROCESS, STATE CHANGE, and
ERRORS :/
The large amount of extra commentary is worth it, IMHO.
Comments are good. Frequent comments are very good - if they are
correct and actually helpful.
I view it this way; if code is not commented, the only explanation is
that the author didn't feel it was worth commenting. Code that is not
worth even a comment, should be removed from whatever project it is in,
to be replaced by something actually worth commenting. (no, I'm not
bashing any particular part of the Linux kernel or anything like that -
this is my personal view for projects that I'm involved in).
However; comments are NOT a substitute for all the other aspects
required for good and reliable code.
Readable. Don't guess what the code does.
Comments are one little part of the larger puzzle. Ignoring their
importance is inexcusable - but they are not the magic silver bullet all
by themselves either.
Of course not. The goal I was aiming for was to create an extremely
structured documentation scheme in the hopes that it would provide a
great deal of ease in understanding what a function does. "if you don't
understand what it does, don't fuck with my code"
My 0.02 Euro
(as someone working on another large project that actually needs
to run reliably)
--
All content of all messages exchanged herein are left in the
Public Domain, unless otherwise explicitly stated.
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/