Re: Gallery's K3 class name/dir/file conventions (was "Capitalization")

Hey Bharat,

So, here's my pass at it.  Tag 3.0.x has 17 class files, and
correspondingly Tag 3.1.x has 17 class files and 17 extension files (34
total).

tag
|-- classes
|   |-- Controller
|   |   |-- Admin
|   |   |   `-- Tags.php
|   |   |-- Tag.php
|   |   |-- TagName.php
|   |   `-- Tags.php
|   |-- Model
|   |   `-- Tag.php
|   |-- Tag                   (**1**)
|   |   |-- Controller
|   |   |   |-- Admin
|   |   |   |   `-- Tags.php
|   |   |   |-- Tag.php
|   |   |   |-- TagName.php
|   |   |   `-- Tags.php
|   |   |-- Model
|   |   |   `-- Tag.php
|   |   |-- Tag.php
|   |   |-- TagBlock.php      (**2**)
|   |   |-- TagEvent.php
|   |   |-- TagInstaller.php
|   |   |-- TagRest
|   |   |   |-- Item.php
|   |   |   |-- ItemTags.php
|   |   |   |-- Items.php
|   |   |   `-- Tags.php
|   |   |-- TagRest.php
|   |   |-- TagRss.php
|   |   |-- TagTask.php
|   |   `-- TagTheme.php
|   |-- Tag.php
|   |-- TagBlock.php
|   |-- TagEvent.php
|   |-- TagInstaller.php
|   |-- TagRest
|   |   |-- Item.php
|   |   |-- Items.php
|   |   `-- Tags.php
|   |-- TagRest.php
|   |-- TagRss.php
|   |-- TagTask.php
|   `-- TagTheme.php
|-- media
|   `-- tag.css
|-- module.info
|-- tests
|   |-- Tag_Item_Rest_Test.php
|   |-- Tag_Rest_Test.php
|   |-- Tag_Test.php
|   `-- Tags_Rest_Test.php
`-- views
    |-- admin
    |   `-- tags.html.php
    `-- tag
        |-- block.html.php
        `-- cloud.html.php

Notes (as annotated above)
1. All actual class code goes in this directory, and all thin
extension-enabling files are outside it.  This makes it easy to browse
code, as you can navigate straight here and ignore everything else.  Also,
note that the *exact* name of this directory is not super important,
provided that all the classes inside it follow its name (and that it
doesn't set a precedent for other devs that ends up causing name
collisions).

2. It's for these files that the exact name "Tag" is important, as Gallery
needs to know to look for TagEvent instead of TAGEvent.  So, we can add a
line to module.info.  BTW, I'm starting to come around to the little-endian
way, as alphabetizing them groups them together.  Of course, there are
other options, too: they could be Tag_Event (which extends Tag_Tag_Event),
Module_TagEvent (which extends Tag_Module_TagEvent), etc., but I'm inclined
to think the simplest one is just TagEvent (which extends Tag_TagEvent).

Thoughts?

Take care,
Shad



On 20 March 2013 17:39, Bharat Mediratta <[email protected]> wrote:

> On Wed, Mar 20, 2013 at 2:59 AM, Shad Laws <shad-xpYdmXCiSuZWk0Htik3J/[email protected]> wrote:
>
>> Hey Bharat,
>>
>> Okay, so here are the two things I've become totally convinced of:
>> - neither of us suck at communicating our thoughts
>> - neither of us are stubborn or inflexible
>>
>> Even if it has the odd side effect of totally reversing our positions at
>> some point in the discussion, I suppose these are still good things :-)
>>
>
> :-)
>
>
>> 1. Did this helper get forgotten or did you intentionally fold it into
>> one of the other rest helpers?
>>
>
> It got forgotten.  It'd be modules/tag/classes/Tag/Rest/ItemTags.php
> I also forgot TagItems and TagItem.
>
>
>> 2. I don't like the idea of calling this directory "Gallery," and would
>> prefer "Module" or "Tag."  The reason I say that is because, for better or
>> for worse, module devs will use the pre-packaged modules as examples of
>> what they should do.  Having their stuff live in the same space as the
>> Gallery core seems potentially bad, and would encumber the "MY_"-style
>> overloading ("class Gallery_Foo extends Gallery_Foo" doesn't seem to work
>> too well...).
>>
>
> Hm.  Yeah, ok that makes sense.  I was following the Kohana example of
> separating "official" from "unofficial".  But you make a good point that
> contrib devs will clone official modules and that'll cause trouble.
>  Assuming that we're expecting modules to override modules, then using
> "Module" is problematic as well, right?  That would mean that we'd want to
> use "Tag".. but that namespace is already in use since Tag_Rest is the
> extension of Gallery_Tag_Rest.  So we'd then have to go to Tag_Rest
> extending Tag_Tag_Rest.  Which means that the bulk of the code lives in
> modules/tag/classes/Tag/Tag/Rest.php.  Oy.  I feel like we'll be explaining
> that oddity to our devs for ages to come.
>
> Perhaps "Core" makes more sense?  Then it'd be Tag_Rest extending
> Core_Tag_Rest (or Tag_Core_Rest).  3rd party modules might have Tag_Rest
> extending Tag_External_Rest which extends Tag_Core_Rest.  But Module is
> semantically equivalent to Core.
>
> So now that I think about it, we can have a consistent label for the base
> implementation class, but overriding modules should use something unique so
> that there's the possibility for multiple overrides.
>
> In the end, I suspect we (or maybe just me) are probably overthinking
> this.  If I had to pick between Module and Core I'd chose Core (shorter).
>
>
>> 3. I like the idea of using the subdirectory both to group these things
>> and uniquify them!  This means we need to define the class prefix "Tag" in
>> the module.info, right?
>>
>
> Why?  We aren't going to enforce it, right?  What do you have in mind?
>
>
>> 4. Which directories are you thinking should be folded into media here?
>>  What's the bigger picture mapping you have in mind for module directories?
>>  Here's my first stab at it:
>> - classes/Controller (controllers)
>> - classes/Model (models)
>> - classes (helpers, libraries)
>> - views (views)
>> - tests (tests)
>> - vendor (vendor, lib)
>> - media (js, css, images)
>> - config (config)
>>
>
> That sounds about right here.  Basically, it seems like there's no point
> to separate out js, css and images.
>
>
>> And a couple others:
>>
>> 5. Obviously, the transparent-extension-enabling files (needs shorter
>> term!) can and should be generated totally systematically.  I'll finish
>> working on the sh script.  I'd also like to make it in bat form to help
>> module devs that do their work on Windows (probably most of them), which
>> leads me to...
>>
>
> I want to avoid telling devs to use a script to generate these files.  I
> hate the "run this script to prepare your code" pattern - adding cognitive
> steps to the dev process makes the whole process feel more cumbersome.  We
> *should* write a test to verify that all of our classes are properly
> extendable and that we don't have any dangling extends.
>
> 6. Although true that contrib modules don't *have* to follow this pattern,
>> I feel like we should promote the idea that they should and make it easy to
>> do so.  I say this because:
>> - It makes things consistent.  Every module gets browsed the exact same
>> way.
>> - It isn't hard.  It's one batch/script file away from being a piece of
>> cake.  This can be rolled into a more comprehensive module/theme template
>> zip file, too.
>> - It would enable modules to modify each other.  Real-world example: the
>> PDF module I just finished needed some tweaks to make it compatible with
>> Movie Overlay, and while I did it without transparent extensions, it'd have
>> been a nice avenue to consider.
>> - It could help future-proof contrib modules down the road, too.
>>
>
> Sounds good.  This is something for the docs that we can evolve over time.
>  I suspect we'll make some more course corrections along the way :-)
>
> So now with all above adjustments, the tree comparison looks like this:
>
> tag tag
> |-- controllers |-- classes
> |   |-- admin_tags.php |   |-- Controller
> |   |-- tag.php |   |   |-- Admin
> |   |-- tag_name.php |   |   |   `-- Tags.php
> |   `-- tags.php |   |   |-- Tag.php
> |-- css |   |   |-- TagName.php
> |   `-- tag.css |   |   `-- Tags.php
> |-- helpers |   |-- Model
> |   |-- item_tags_rest.php |   |   `-- Tag.php
> |   |-- tag.php |   |-- Tag
> |   |-- tag_block.php |   |   |-- Block.php
> |   |-- tag_event.php |   |   |-- Core
> |   |-- tag_installer.php |   |   |   |-- Controller
> |   |-- tag_item_rest.php |   |   |   |   |-- Admin
> |   |-- tag_items_rest.php |   |   |   |   |   `-- Tags.php
> |   |-- tag_rest.php |   |   |   |   |-- Tag.php
> |   |-- tag_rss.php |   |   |   |   |-- TagName.php
> |   |-- tag_task.php |   |   |   |   `-- Tags.php
> |   |-- tag_theme.php |   |   |   |-- Model
> |   `-- tags_rest.php |   |   |   |   `-- Tag.php
> |-- models |   |   |   |-- Tag
> |   `-- tag.php |   |   |   |   |-- Block.php
> |-- module.info |   |   |   |   |-- Event.php
> |-- tests |   |   |   |   |-- Installer.php
> |   |-- Tag_Item_Rest_Helper_Test.php |   |   |   |   |-- Rest
> |   |-- Tag_Rest_Helper_Test.php |   |   |   |   |   |-- Item.php
> |   |-- Tag_Test.php |   |   |   |   |   |-- Items.php
> |   `-- Tags_Rest_Helper_Test.php |   |   |   |   |   `-- Tags.php
> `-- views |   |   |   |   |-- Rest.php
>     |-- admin_tags.html.php |   |   |   |   |-- Rss.php
>     |-- tag_block.html.php |   |   |   |   |-- Task.php
>     `-- tag_cloud.html.php |   |   |   |   `-- Theme.php
>  |   |   |   `-- Tag.php
> 6 directories, 26 files                  |   |   |-- Event.php
>                                          |   |   |-- Installer.php
>                                          |   |   |-- Rest
>                                          |   |   |   |-- Item.php
>                                          |   |   |   |-- ItemTags.php
>                                          |   |   |   |-- Items.php
>                                          |   |   |   |-- TagItem.php
>                                          |   |   |   |-- TagItems.php
>                                          |   |   |   `-- Tags.php
>                                          |   |   |-- Rest.php
>                                          |   |   |-- Rss.php
>                                          |   |   |-- Task.php
>                                          |   |   `-- Theme.php
>                                          |   `-- Tag.php
>                                          |-- media
>                                          |   `-- tag.css
>                                          |-- module.info
>                                          |-- tests
>                                          |   |-- Tag_Item_Rest_Test.php
>                                          |   |-- Tag_Rest_Test.php
>                                          |   |-- Tag_Test.php
>                                          |   `-- Tags_Rest_Test.php
>                                          `-- views
>                                              |-- admin
>                                              |   `-- tags.html.php
>                                              `-- tag
>                                                  |-- block.html.php
>                                                  `-- cloud.html.php
>
>                                          17 directories, 44 files
>
>

------------------------------------------------------------------------------
Everyone hates slow websites. So do we.
Make your web apps faster with AppDynamics
Download AppDynamics Lite for free today:
http://p.sf.net/sfu/appdyn_d2d_mar

__[ g a l l e r y - d e v e l ]_________________________

[ list info/archive --> http://gallery.sf.net/lists.php ]
[ gallery info/FAQ/download --> http://gallery.sf.net ]