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

[Les Mikesell]

On Sun, 2006-01-01 at 00:56, David G. Miller (aka DaveAtFraud) wrote:

> > Regular expressions are a feature that could use more documentation
> > than they usually get.
> >
> > {o.o}
> 
> Ever since serving said sentence, I have been of the opinion that all 
> newly minted programmers should first serve time in the purgatory known 
> as "software maintenance programming."  Only after getting an 
> appreciation for how hard it is to divine someone else's obscure code 
> should they be unleashed on the world and allowed to create their own 
> inscrutable incantations.

Very good point.  The thing that needs to be documented is
what the routine is expected to do and perhaps any quirky
side effects, not the step by step operations which are
obvious from the code itself.  The maintainer needs to
know what the code is supposed to be doing, not so much
what it actually does or how it does it because the reason
he's in there in the first place is to fix it.  And the
really messy parts (and very common) are where someone else
already changed the logic but left some old misleading comments.

> That being said, I probably do most of my current development in perl 
> which has been described as a "write only" language.  I prefer to call 
> it the Swiss Army Knife of programming languages.

The great thing about perl is that nearly everything you might
need is already done as a module on CPAN, so your own code
ends up being just a control loop calling existing, already
documented functions. 

-- 
  Les Mikesell
    lesmikesell at gmail.com