jdow wrote:
Negative. Undocumented code is "a bad thing." Sadly, we all seem to
An overview of the program and its basic algorirthms is good. It's relatively static, less inclined to become out of date as bugs are fixed.
A detailed description of the syntax and semantics of the language are a separate matter.
commit to much of it. We presume the next poor sod who gets to play with the code will understand the subtleties of the language and see what we're doing instantly. We discover, when we are the next poor sod some years down the line that we've forgotten that language after picking up 7 others.
I tend to ignore comments when bug-hunting as, while they may describe that author's intent, they are likely to mislead in the debugging process.
Sun (in Java) recommends an overview at the start of the file, and a description of each function's purpose, inputs and outputs.
Regular expressions are a feature that could use more documentation than they usually get.
But every place they're used is not the place to document them. If you want to know about them,
man 7 regex -- Cheers John -- spambait 1aaaaaaa@xxxxxxxxxxxxxxxxxxxxxxx Z1aaaaaaa@xxxxxxxxxxxxxxxxxxxxxxx Tourist pics http://portgeographe.environmentaldisasters.cds.merseine.nu/ do not reply off-list
