[wp-hackers] Inline Documentation Effort was a Failure
wordpress at dd32.id.au
Thu May 22 04:21:21 GMT 2008
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
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
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:
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
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>
More information about the wp-hackers