Bad API (12 posts)

I'm new to WP and i'm trying to make my home page display something else other than the posts in coronogical order. I come from a C# background and I don't know any php. But i can see that it's not that hard to pick up.

i'm reading the example of using have_posts() and the_post() and the_category and whatever else there and I want to say whoever designed this API has no concept of what object oriented design is and has never heard of objects.

why should i do have_posts() when i can do foreach loop? why can't i do $post->categoryID to access the category of the post? etc ect.. just bad design.

If you want to do that sort of thing, there's nothing preventing you from doing it that way (in most cases). A lot of people find these template functions simpler.

However, for your specific case of category... A post can be in multiple categories, not just one. So $post->categoryID doesn't make sense. Category would be an array and such. No biggie, a lot of people forget this.

For the most part, the internal design does make sense in the way you're thinking. These functions are there to make things simpler. But if you want, you can create a new WP_Query object, call get_posts() and then foreach through the $posts it returns all you like. And yes, you can do foreach ($post in $your_query->$posts) { echo $post->$content; ... } and so on.

It works, but it's not the most obvious way to a lot of people. It's certainly not the most obvious way to non-programmers, and template designers are frequently not programmers.

Although it could be as easy as $post->title etc., it doesn't give you a large range of options, not does it allow you to pre-format anything, nor does it allow plugins to interact with it, nor does it allow designers easy, standardized access to values.

Fr example I am currently writing a plugin that has to modify almost everything the database spits out -- everything from post content to permalinks to category names you name it. Because most themes call wp_the_category_list (which spits out an HTML list of the categories) to list their categories I am able to write a function that takes that code and 'hooks' into it and modifies it without worrying that it will only work on some themes, but not others.

Plugg-ability is the main goal of WordPress.

Although I have to admit sometimes I wonder if the fact that the developers use PHP has influenced them in a bad way. Some of the sections are built just like PHP is. *shudders* (Not in a good way.)

No he hasn't given any example. He was referencing to functions not classes. If his critique was about the object model, he should critisize a class like WP_User or WPDB. It is totally legetimate to have functions and classes coexist in the same domain of code - and so does WordPress. This is not necessarily bad design by default.

It may be that darages intention was to further generalize his critique to say "The WordPress API is rotten". Well, in my point of view this is a statement that needs more examples than pointing to two functions.

I don't want to say darage isn't right. But his examples are poor and so may his conclusion.

I may have a better example: The WPDB class stores the names of the tables. So far okay. But why isn't the table_prefix also stored in this class? Why do the user of WPDB have to set the table name members directly from outside of the class and not with methods - or *gasp* why not setting prefix and table names during construction of WPDB. Thats REALLY poor design!

Don't get me started on poor design: I have spent that last few days reading almost every line of code in 2.1 while working on my plugin, and there are some things that make me want to tear my hair out, but I don't think it is as bad as he lets on.

As for your example, probably because you input $table_prefix before the class is even created, and in doing so you keep wp-config nice and clean for those who get scared by code.

I would note that have_posts() etc., the components that make up what we call The Loop, the various "template tags," are a sort of compromise* between straightforward PHP and a template framework for the non-programmer to work with. WordPress is a weblogging tool, not a developer platform, and as Otto points out not every WordPress user will be coming to it from a programming background.

I would also say that feedback of this sort is given more import when it's apparent the person giving it has taken time to figure out how WordPress actually works behind the scenes, and learned a little about the tools the developers try to provide for modifying its behavior.

Wow.. thanks all for the replies. I didn't mean to insult anybody but i wrote the post in the most blunt manner to get the point across. the_categories() function is one example of a bad approach to an api design because it returns an unordered html list which is a clear mix between formatting and behavior. for example if i wanted to return the categories is a div list instead i have no choice but to not use the the_categories() function.. but if the function just returned a list of categories and left it for me to choose how to format the output it would've made it easier for me than using sql queries.

The sole function of a good api is provide reuse and hide implementation so that i don't have to go the database and understand the data model in order to achieve what i want to do. Another principle it to facilitate reuse and flexibility which is not achieve by above function.

another thing, naming conventions are really poor. For example the_categories is a really bad name for the following reasons:

1. why prefixing it with the? it doesn't add any information no?
2. function names should be verbs that explain what the functions do. for example get_categories() would've been a better function name (although im not a fan for underscores but that's another issue).
3. it's not obvious from the name that the function returns a formated list.. so maybe it should've been get_formatted_category_list(). of course it's better that the function doesn't return formatted output.

and so on and so forth.. i didn't even go into how the parameters are constructed.

another bad naming is prefixing things with WP, why is that? it is absolutely unnecessary and i can't find any reason for it.

for those who argued that the api is designed for non programmers. for me who esle is going to use an api other than a programmer?

1. Well, there's the_title(), the_author(), the_content() ... I can go on, but it's clear the use of the_ for function name prefixes is a mere naming convention, partly owed to WordPress' evolution from b2. You don't like it, fine. However, how does WordPress function nomenclature refer to your original points?

2. Like say get_the_category() -- which exists in the core and fits with your idea of an "API" of sorts (but see below).

the_category() echoes or prints the categories, whereas get_the_category() returns them. Two different functions doing nearly the same thing; hopefully the naming convention in play here defines the 'nearly' well enough.

3. True. But then all the documentation on it states what it does (hence the reason for the documentation?). And I imagine for most people having template functions like display_formatted_html_unordered_category_list() would be overkill, as well as difficult to remember.

You say you come from a development (C#) background. With such a background, I expect you to understand that the terminology (and how it is used) is important. So with that in mind: the_category() (there is no the_categories()) is not what we mean when *we* refer to an API. Around here API refers to the 'hooks' and whatnot that can be used (by programmers!) to modify how WordPress behaves and what it returns, or to work around it's built-in functionality so one may use their own, and many of these hooks are designed for plugin development. In regards to the_category() et al, in WordPress parlance these are known as template functions or template tags. They are not an interface into WordPress but rather a framework for displaying the various elements of ones blog. Anyone designing (or editing) theme templates will need to know about them and what they can (and cannot) do with them, but I nor I think they would refer to themselves as programmers for just making use of them.