Why questions don't get answered, or "No, I've already RTFM, tell me the answer!"

[John Summerfied]

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 at computerdatasafe.com.au  Z1aaaaaaa at computerdatasafe.com.au
Tourist pics http://portgeographe.environmentaldisasters.cds.merseine.nu/

do not reply off-list