Posted by Jerry Stuckle on 07/08/07 03:35

gosha bine wrote:
> pangea33 wrote:
>>
>> Any "professional" programmer who relies on the vast repository of
>> *documentation* present in most projects in industry is either an
>> idealistic novice, or EXTREMELY fortunate for the places they've
>> worked.
>>
>
> That's the point where I tend to agree with you. Documentation should
> document behaviour, not syntax. The best documentation for the syntax is
> the source itself.
>
>

And this is where I disagree with you. How a function goes about doing
something is immaterial. What is important is the syntax of calling the
function and an *overview* of the behavior.

Do you use the PHP source code to figure out how to call fopen()? Do
you even know how fopen() does its job?

All you really need is the same thing that's in the PHP doc - function
name, parameters, an overview of what it does (NOT how it goes about
doing its job) and return value.

IOW, KISS. Trying to understand how functions work is unnecessary
detail - detail which will get you confused even on a relatively small
project.




--
==================
Remove the "x" from my email address
Jerry Stuckle
JDS Computer Training Corp.
jstucklex@attglobal.net
==================

[Back to original message]