[wp-hackers] Clarification of wp-includes/class folder

[Jacob Santos]

The last time I bought this up, it was well received, or so I thought. 
However, the bug and patches on Trac were not. 
<http://trac.wordpress.org/ticket/4899>.

It is against my religion to willfully add a closing PHP tag to a class 
file. I'm a firm believer of this religion. Since it is a coding 
standard, I will add them. However this ticket should be looked at. 
<http://trac.wordpress.org/attachment/ticket/4901/cleantrailingspaces.diff> 
for a list of potential files which may give problems in some edge 
cases. The main area of concern is wp-includes/*.php.

A few points bought up in the ticket:

1. Class Folder name
2. Small amount of classes

Rest of the discussion was on the lack of closing PHP tag.

I however gave four justification points. Not to say that at least a few 
of them can easily be crushed with a good argument, but it would at 
least allow me to better explain my thoughts.

   1. Allows for Classes to be Unit Tested easily. Some classes are
      within files that contain presentation, which doesn't easily allow
      for unit testing the class.
   2. Single location to find classes, moves classes that are within
      other files into a location where developers and plug in authors
      can find them. Intuitive locations.
   3. Submitting Patches for classes should allow for better versioning.
   4. Possible optimization by only including the classes that are
      needed. (Think Administration or installer)

The main justification is that moving forward, PHP 4 will be left 
behind, eventually at some point and __autoload will be of some use. 
Whether or not it is a dirty hack is irrelevant. Providing for this and 
following the PEAR class folder scheme, I've found is a lot easier to 
find classes, since the folder scheme is directly related to the class 
name. In wp-classes.php, you should expect to find all WordPress 
classes, but not so. WP_Rewrite is in rewrite.php. If you are lucky, 
you'll only have to look once, if you are unlikely you would have to 
look at two places. However, without looking at the codex, where would 
you expect to find WP_Ajax_Response? wp-classes.php perhaps? I've found 
it once, and even now I have no idea. *I should know where to look the 
first time, than constantly searching.*

On the name of the folder, wp-includes/class is just my preference for 
the patches. It can be whatever. I will however debate my reasoning for 
using that folder name.

1. wp-includes/classes/WP/Cache.php
2. wp-includes/class/WP/Cache.php

Looking at it, it seemed intuitive, since I'll want to be including a 
single class, named WP_Cache. However, thinking as the folder is holding 
many classes, wp-includes/classes/ would make more sense. Whatever. I'll 
just be happy with having a folder for classes.

For the second point against this setup, what happens at which point 
when WordPress does get even more classes and the discussion comes up 
again? "We shouldn't do that since we have too many classes and it would 
be too much work to move the classes." Now is the best time, as it 
allows for the most forward outlook and minimal work.

I'm sure that once this is set in place that many people would be on 
board, since its advantages have to be seen for themselves. However, 
seeing classes in many different places is madness. Why wp-includes 
exists and yet there are functions and classes in other base files and 
in the wp-admin is beyond me. It is a disadvantage and causes more 
headaches to developers looking to extend WordPress and in some classes 
causes extra work since the functions would have to be rewritten since 
the file its in has output that would need to be captured.

I would recommend that all functions and classes be, at the very least 
and if we can agree on anything, in wp-includes.

Jacob Santos