[wp-hackers] Inline Documentation Effort was a Failure

[James Davis]

DD32 wrote:

> Developers like Clean code, Clean code is usually relitivly easy for a
> developer to read, I personally have not been involved in WordPress for
> a long time, But i can look at a function name, and its arguements, and
> have a pretty good idea of what it takes in, and what its likely to return.
> Those new to WordPress, or who do not understand the inner workings,
> Cannot make assumptions like that.
...
> I cant count the number of times i've come accrossa bug in some
> software, And then spent hours attempting to figure out what the heck is
> going on, After working for a few hours, I'm likely to throw a comment
> here, maybe one there, But i'm unlikely to want to write up a paragraph
> of notes on the exact function or nature of a function.

I can get frustrated checking out bug reports that relate to an
undocumented or uncommented function. From a quick look at the function
you can usually get an idea of the concept of the function but the bug
almost always lies in the subtleties of the function. Is it a bug? Did
the author intend it to work that way, if so, what depends on that behavior.

I'm just as guilty of it myself
(http://trac.wordpress.org/ticket/6842#comment:12) where I should have
at least left a comment as to why I'd not replaced the key generation
code with wp_generate_password() despite the key generation and password
generation being identical at that stage. I'll learn next time :-)

James

-- 
http://www.freecharity.org.uk/ - Free IT services for charities
http://www.freecharity.org.uk/wiki/ - The VCSWiki