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

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 :-)

----

Looking at this again this morning, I think I'm starting to come back
around to my original (and your current) position: we should stick with K3
strict conventions.  Like you pointed out, this will make it easier to
incorporate 3rd-party modules and may help future-proof us later on.  I
felt the same as you when I first started - the extra layers of hierarchy
were weird.  But then again, it does make it easy to figure out inclusion
paths.

I have a few other thoughts, most of which can be illustrated with your tag
example.  I added a few annotations and copied it below:

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    |   |-- Gallery           (**2**)
|   |-- item_tags_rest.php (**1**)    |   |   |-- Controller
|   |-- tag.php    |   |   |   |-- Admin
|   |-- tag_block.php    |   |   |   |   `-- Tags.php
|   |-- tag_event.php    |   |   |   |-- Tag.php
|   |-- tag_installer.php    |   |   |   |-- TagName.php
|   |-- tag_item_rest.php    |   |   |   `-- Tags.php
|   |-- tag_items_rest.php    |   |   |-- Model
|   |-- tag_rest.php    |   |   |   `-- Tag.php
|   |-- tag_rss.php    |   |   |-- Tag           (**3**)
|   |-- tag_task.php    |   |   |   |-- Block.php
|   |-- tag_theme.php    |   |   |   |-- Event.php
|   `-- tags_rest.php    |   |   |   |-- Installer.php
|-- models    |   |   |   |-- Rest
|   `-- tag.php    |   |   |   |   |-- Item.php
|-- module.info    |   |   |   |   |-- Items.php
|-- tests    |   |   |   |   `-- Tags.php
|   |-- Tag_Item_Rest_Helper_Test.php    |   |   |   |-- Rest.php
|   |-- Tag_Rest_Helper_Test.php    |   |   |   |-- Rss.php
|   |-- Tag_Test.php    |   |   |   |-- Task.php
|   `-- Tags_Rest_Helper_Test.php    |   |   |   `-- Theme.php
`-- views    |   |   `-- Tag.php
    |-- admin_tags.html.php    |   |-- Model
    |-- tag_block.html.php    |   |   `-- Tag.php
    `-- tag_cloud.html.php    |   |-- Tag
   |   |   |-- Block.php
6 directories, 26 files    |   |   |-- Event.php
   |   |   |-- Installer.php
    |   |   |-- Rest
   |   |   |   |-- Item.php
    |   |   |   |-- Items.php
   |   |   |   `-- Tags.php
    |   |   |-- Rest.php
   |   |   |-- Rss.php
    |   |   |-- Task.php
   |   |   `-- Theme.php
    |   `-- Tag.php
   |-- media                 (**4**)
    |   `-- 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, 41 files

Following the four marks above:

1. Did this helper get forgotten or did you intentionally fold it into one
of the other rest helpers?

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...).

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?

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)

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...

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.

Thoughts?

Take care,
Shad



On 19 March 2013 23:21, Bharat Mediratta <[email protected]> wrote:

>
> Whew!  I had to read this 2 and a half times.  I think all this discussion
> has lead me to some conclusions:
>
> 1) We *can* tinker with autoloader and convert some of the duplicated
> files into magic.
> 2) We *should not* do #1.  We should try living with the K3 file
> duplication for now
> 3) We *should* make all classes in the gallery modules overloadable, *even
> * ones that are likely to be unsafe to overload like the installers, etc.
> 4) We *should try* the simplest approach here, even if it results in more
> depth.
>
> I think we've both mostly reversed positions :-)
>
> What would this look like?  Here's a mapping of the tag module:
>
> 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   |   |-- Gallery
> |   |-- item_tags_rest.php   |   |   |-- Controller
> |   |-- tag.php   |   |   |   |-- Admin
> |   |-- tag_block.php   |   |   |   |   `-- Tags.php
> |   |-- tag_event.php   |   |   |   |-- Tag.php
> |   |-- tag_installer.php   |   |   |   |-- TagName.php
> |   |-- tag_item_rest.php   |   |   |   `-- Tags.php
> |   |-- tag_items_rest.php   |   |   |-- Model
> |   |-- tag_rest.php   |   |   |   `-- Tag.php
> |   |-- tag_rss.php   |   |   |-- Tag
> |   |-- tag_task.php   |   |   |   |-- Block.php
> |   |-- tag_theme.php   |   |   |   |-- Event.php
> |   `-- tags_rest.php   |   |   |   |-- Installer.php
> |-- models   |   |   |   |-- Rest
> |   `-- tag.php   |   |   |   |   |-- Item.php
> |-- module.info   |   |   |   |   |-- Items.php
> |-- tests   |   |   |   |   `-- Tags.php
> |   |-- Tag_Item_Rest_Helper_Test.php   |   |   |   |-- Rest.php
> |   |-- Tag_Rest_Helper_Test.php   |   |   |   |-- Rss.php
> |   |-- Tag_Test.php   |   |   |   |-- Task.php
> |   `-- Tags_Rest_Helper_Test.php   |   |   |   `-- Theme.php
> `-- views   |   |   `-- Tag.php
>     |-- admin_tags.html.php   |   |-- Model
>     |-- tag_block.html.php   |   |   `-- Tag.php
>     `-- tag_cloud.html.php   |   |-- Tag
>    |   |   |-- Block.php
> 6 directories, 26 files   |   |   |-- Event.php
>    |   |   |-- Installer.php
>    |   |   |-- Rest
>    |   |   |   |-- Item.php
>    |   |   |   |-- Items.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, 41 files
>
>
> Note that I took some liberties with the views and tests.
>
> So what does this mean?
>
> We're adding 11 directories and 15 files to the distribution.. *But* you
> can follow the path of inclusions relatively easily *and* it's internally
> consistent with the Kohana 3 code we ship *and* it's consistent with
> where Kohana 3 is going so pulling from Kohana upstream will be less
> impactful.
>
> The gallery codebase is going to be larger - but contrib modules don't
> have to follow this pattern!  They can extend but not be extensible if they
> choose which means that they can write a lot less code if the want.
>
> By being consistent it's easier for us to pull in other 3rd party Kohana
> modules (see http://kohana-modules.com/) and use them without
> modification.
>
> thoughts?
>

------------------------------------------------------------------------------
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 ]