On Sun, Jun 04, 2006 at 02:02:09PM -0700, Andrew Lentvorski wrote: > 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. >
I have an even better idea: Avoid clever algorithms altogether. Oh, wait, that wasn't my idea ... it was from Kernighan and Plauger in "The Elements of Programming Style." -- Lan Barnes Linux Guy, SCM Specialist Tcl/Tk Enthusiast -- [email protected] http://www.kernel-panic.org/cgi-bin/mailman/listinfo/kplug-list
