ember-pods-structure-proposal.md

I first heard the details about the new pod structure proposal at the F2F meeting. Since this structure has been discussed so extensively among the core team that many consider themselves "frog-boiled", I thought it could be helpful to hear the initial impressions of a fresh frog in the pot.

I've tried to document my first impressions of the "new pods structure" ("NPS") proposal and evaluate its advantages and disadvantages compared to the classic structure ("CS") and the "old pods structure" ("OPS").

I've also prepared a proposal for an alternative structure called Pods+, which is a bit of a merger of CS, OPS, and NPS.

New Pods Structure

For the sake of discussion, here's an example of the new pods structure:

app
  components
    list-paginator
      component.js
      template.hbs
  controllers
  helpers
  models
    posts
      model.js
      serializer.js
      adapter.js
  routes
    posts
      components
        post-editor
          component.js
          template.hbs
          components
            post-editor-button
              component.js
              template.hbs
        post-viewer
          component.js
          template.hbs
      helpers
        capitalize.js
        titleize.js
      routes
        new
          components
            new-post
              component.js
              template.hbs
          route.js
          template.hbs
      template.hbs
  services
  templates
  app.js
  router.js

Advantages of NPS

• It is sufficiently flexible to allow for any realistically required level of specialization. This is a big win over the interim pods structure.

• Its nested structure allows for easily finding broad and specialized forms of any module.

• It can coexist with the CS in a single app.

Disadvantages of NPS

• The structure is quite verbose and results in long paths which may cause problems in editors when viewing a project tree, as well as the bizarre Windows path-length limitation.

• Any specializations at a route require that the routes segment be repeated at least once in a full path.

• The name "pods" is overloaded in Ember developers' minds, since it's been used for a while with the OPS.

• It can NOT coexist with the OPS.

• Requires moving entire subdirectories in order to support adding a single local override, such as a localized helper.

Pods+ Proposal

The Pods+ structure borrows elements from the NPS, and can coexist with the CS and OPS.

Here is the above example expressed using Pods+:

app
  components
    list-paginator
      component.js
      template.hbs
  controllers
  helpers
  models
    posts
      model.js
      serializer.js
      adapter.js
  routes
    posts
      +components
        post-editor
          component.js
          template.hbs
          post-editor-button
            component.js
            template.hbs
          +helpers
            calculate-post-title.js
        post-viewer
          component.js
          template.hbs
      +helpers
        capitalize.js
        titleize.js
      new
        +components
          new-post
            component.js
            template.hbs
        route.js
        template.hbs
      template.hbs
  services
  templates
  app.js
  router.js

Note the following:

• The top-level can be structured the same as the top-level of the CS.

• Any nesting within other levels is assumed to remain the same type (i.e. route, component, etc.) unless explicitly overridden by a directory named +<type>.

• Within each route, template.js, route.js, and controller.js can be defined directly, just like in the OPS. component.js could also be defined for routable components.

• Specializations are allowed to be added beneath a +<type> segment at any route level. These specializations are scoped to the route's module, just like in NPS. Only certain classes, like components and helpers, are allowed to be specialized.

• The models directory structure matches that from the NPS.

Advantages of Pods+

I believe that Pods+ has the same advantages as the NPS, plus the following:

• Can coexist with both CS and OPS.

• Is additive to the pods structure, and therefore doesn't require moving subdirectories in order to add a specialization to a route.

• Directory paths are shorter than in NPS, especially for deep routes.

  • Path in NPS example (8 segments, 60 chars): app/routes/posts/routes/new/components/new-post/component.js

  • Equivalent path in Pods+ example (7 segments, 54 chars): app/routes/posts/new/+components/new-post/component.js

  • This advantage grows by one segment and 6 chars per level of nesting.

• No structural buckets, like routes, are repeated as segments in paths.

• + is a strong but simple signal for specializations. It indicates that specialized modules, such as components, are additive (i.e. they override lower-level modules of the same key).