[wp-hackers] Re: 1.5.2 or on to 1.6?

[Scott Merrill]

Martin Geisler wrote:
>>I also believe that well-written code usually doesn't need comments
>>unless it's doing some sort of voodoo or workaround. (See
>>gettext.php.)
> 
> 
> Is this not a rather bad example?  I mean, that file comes from an
> external project, who obviously know how to write proper doccomments.
> 
> And the idea that there can be such a thing as well-written code
> containing no comments is bogus: it is only in small toy examples that
> the function and argument names are enough to determine what a
> function does.

Comments are _extremely_ helpful to fledgling programmers and hackers.
I've been cutting my programming teeth on WordPress, and it's been an
awful lot of trial and error as I work through the code at different points.

For some things, it's enough to look at a function name and it's list of
accepted arguments, plus its return value.  But the return value can be
sent back at several different points along the way, which means I need
to work through the function to see what may be returned, and where.

For other things, it can be quite a challenge to determine what's
happening, and why.

I'd love to see all the functions at least have a modest comment block
stating accepted input, and what it returns.  This would help other
fledgling coders.  Yes, it will bloat the file sizes a bit, but text
compresses well, and comments won't add any delay to program execution.

-- 
skippy at skippy.net | http://skippy.net/

gpg --keyserver pgp.mit.edu --recv-keys 9CFA4B35
506C F8BB 17AE 8A05 0B49  3544 476A 7DEC 9CFA 4B35