Gregory K. Ruiz-Ade wrote:
On Jun 3, 2006, at 5:35 PM, Andrew Lentvorski wrote:
So, what is proper documentation, pray tell?
worst case? At a minimum, an explanation in the comments of the code
explaining what a block of code does. Personallly, I tend to put in the
comments first to remind myself what it is I'm trying to do, then I
start fleshing out blocks of code for each task, and if I had to change
tactics or replace an algorithm, update the comments to fit. It really
doesn't take that much longer than doing the code only, and makes it
much easier to understand.
When there are lots of hands touching code, this just isn't feasible.
The code has to speak for itself.
Any time you think you're being clever in code, comment your
cleverness. This has saved me time on fixing bugs in my own code many
months later. I came up with a really nice one-line snippet of code for
whatever it was doing, and six months later spend the better part of a
day figuring out why it wasn't handling a new case. Sure, the comment
explaining it would have been as long as this paragraph, but man it
would have saved me time.
No argument. A friend of mine calls it "psychic commenting"; whenever
he hits a clever section he invariably sees a comment right there. I'm
very good about being straightforward. When I am not, there is a
comment. Generally with a hyperlink to the external reference, as well.
-a
--
[email protected]
http://www.kernel-panic.org/cgi-bin/mailman/listinfo/kplug-list
