General code / workflow questions

1. You can write a quick and simple plugin to replace classnames with those you want to use, although I find it useful that every WordPress install I work on uses the same ones.

2. If you’re retrieving, for example a *list* of categories, it makes sense that it comes in ul tags. This is not presentation, this is semantically-correct markup, a benefit for which WordPress is famous. You can use CSS to style the returned list in any way you want.

3. These things take time; most of the developers are busy developing. “Crap,” eh? Way to show appreciation for the time and effort that other volunteers have put in. Think you can do better? Prove it.

Kalessin,
Thanks for the reply.

1. Ok. So you’re saying it’s best to write my own custom functions? Using raw data where I can, and regexp-ing the rest? Sounds doable.
And I get your point about the standard install.

2. I’m all up on semantic markup. I’ll rephrase (and possibly edit the original post’s question) was why is *data* and *markup* mixed. (This is really a follow-on question from #1)

3. Oh come on! The effort it takes to write a function definition is negligible!! Writing a function might take hours, days, or even weeks.

A definition that extracts the arguments, and specifies the return type, would take 5 minutes. A basic example perhaps another 10!

As I’ve said, with little consistency in function return-types, I’d waste more than 5 minutes trying to work out what’s going on. Multiply that by 1000s of users and… well, you get the picture.

“Memo to all staff: please document your functions, then email the webmaster who will publish them online.”

With regards to me putting in the effort, I understand where you’re coming from, but a misplaced work ethic I think:

“All of the documentation at the Codex has been produced by users like you and me!” reads to me as “We can’t be assed to finish the job! We’d rather get onto something more interesting!”

Let’s get everyone up to speed with the basics of documentation then let the newly-informed give something back once they know what the hell is supposed to do what.

I’m ALL up for development time, but this is a job half-done, I’m afraid, and you’re not going to be changing my mind on this one.

In this age of web apps and free frameworks, documentation is a prerequisite.

https://docs.jquery.com/Main_Page
https://www.prototypejs.org/api
https://codeigniter.com/user_guide/toc.html

Thanks for the input,
Cheers,
Dave

To be fair, I kind of agree with you on point three. Proper documentation of a function takes a fraction of the time of the original function development. However, there may be myriad reasons for not properly documenting, such as

• a developer wrote the function(s) then lost interest in the project before writing the documentation
• many functions were written before WordPress was big enough for documentation to be important
• a non-programmer took on the task of documenting the functions and never bothered to complete

These are just guesses. My point is that for whatever reason, it hasn’t been done and berating volunteers for this being “crap” when they’ve clearly worked hard in other areas seems a little… ungrateful, I guess. Just could have been put in a more diplomatic manner.

>> Just could have been put in a more diplomatic manner.

A fair point! I didn’t realise that it was all done by you and I.

To be clear, I wasn’t actually slagging the documentation that’s been done, I was slagging the fact it’s incomplete which is a higher-level (management) issue.

Thanks to everyone who’s contributed!

Cheers,
Dave