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

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 ]