[wp-hackers] Inline Documentation Effort was a Failure

[DD32]

One word, Lazy.   (For anyone who reads this paragraph, and doesnt bother  
to read the rest, Please read Paragraph 6 before flaming)
Developers are lazy people in general, If something does not give them a  
benefit in the imminent future, chances are, its not likely to be taken.

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.

Inline Documentation is a great thing, It documents functionality, It  
paves the way for future developers to understand what they're looking at,  
It adds extra time to the coding process.
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.

Developers do not generally have a English Degree, I personally only speak  
English, I barely understand any other language, But give me a programming  
language and it'll be easy. I find documentation hard to write, Its not  
only the phrasing, But keeping it concise and to the point, while being  
readable to other people.
Swing back to the first point, Developers are lazy, I could spend some  
time in learninghow to write good documentation, Infact, I *should* do so,  
However, I have not yet been forced to, Or had a huge need to.

I personally know how hard it is to go through an make lots of changes to  
code, knowing that had people been a bi more careful while making changes,  
they could've ended up with cleaner code.
I mean, Just look at all the extra variable references i striped out:  
http://trac.wordpress.org/ticket/5418 Most were left over from when API  
was added, or another function deprecated. Quite a lot of the code was  
still there, simply as it didnt affect the running of WordPress (Other  
than taking up a few ms).


Not all Developers are Lazy, Some have English Degrees, Some do not speak  
English Fluently, Some enjoy making large sweeping changes, And even those  
in worse positions than me, Can Write good inline documentation(Or not so  
good even, But they still try, and get the point accross).

Inline documentation is great, It helps everyone, But keeping it updated  
is another matter, Most coders enjoy the coding, Not the writing. Most of  
the patches submitted to trac do not include Documentation either, Quite  
often, A diff is commmited directly without too much editing by the look,  
Nothing against the commiter, But fact is, Those who do the commits do not  
allways have the time to add extra documentation, The patch submitter is  
most likely just wanting to fix the bug rather than explain what the code  
does.


I'm aiming to add documentation to any new functions, or any code which is  
not self explanitory which I myself write, Simply because, My logic can be  
weird at the best of times, I dont trust others to know what *my* mind is  
thinking.

And while i'm on it, Great thanks to mdawaffe for the documentation on the  
Revisions, Was much easier to understand how the Revisions were being  
handled with the commenting in the code:  
http://trac.wordpress.org/changeset/7747

I know some people are not going to agree 100% with this post, But i also  
know some people will not agree with the parent post either,  
"Documentation is bloat, it jsut increases the code size!", etc.

(For reference: Yes, Documentation probably adds a fair few KB to each  
file, most of hte diffs i saw were in the area of 20+KB, But PHP is  
efficient at ignoring comments, The only real extra delay is loading from  
the filesystem, And if and extra bit of code loading time really makes too  
much of a difference to performance, Your server needs to look into an  
opcache solution)

Jacob, The documentation wasnt a waste of your time at all, Thank you for  
all the docs, Really, Thank you, It'll be a shame if its the only real  
documentation in the code, But i'm sure many people have allready been  
helped by it.
As to writing more, If you do, Great for you :), If you dont, Then i dont  
blame you. In order to continue you need support, And if theres no support  
there from major devs, then you dont get very far.

On Thu, 22 May 2008 13:41:30 +1000, Jacob Santos <wordpress at santosj.name>  
wrote: