Implement the "Best Practice Recommendations for Angular App Structure" by Google

[trevordmiller]

Are you going to implement the "Best Practice Recommendations for Angular App Structure" by Google? https://docs.google.com/document/d/1XXMvReO8-Awi1EZXAXS4PzDzdNvV6pGcuaF4Q9821Es/pub

[addisonedwardlee]

@trevordmiller I've actually got an existing PR https://github.com/angular/angular-seed/pull/210 to match the Best Practices. Take a look and tell me what you think!

[mbroadst]

@trevordmiller there's also another pull request here (https://github.com/angular/angular-seed/pull/164) that I believe follows the guidelines more closely. Please add your feedback so we can move one way or another.

[petebacondarwin]

Please comment here on how to move forward with this refactoring.

[petebacondarwin]

One layout is:

app/                          --> all of the files to be used in production

  assets/                       --> all static asset files
    css/                          --> css files
      app.css                       --> default stylesheet
    img/                          --> image files

  components/                   --> common app components (service, filters, directives)
    directives/
      appVersion.js               --> custom directive that returns the current app version
      appVersion_test.js          --> tests for application level directives
    filters/
      interpolate.js              --> custom interpolation filter
      interpolate_test.js         --> tests for application level filters
    services/
      appVersionService.js        --> custom service that returns the current app version
      appVersionService_test.js   --> tests for application level services

  view1/                        --> the view1 subsection
    view1.html                    --> the template rendered for this feature
    view1.js                      --> the application logic for this feature
    view1_test.js              --> tests for view1 logic

  view2/                        --> the view2 subsection
    view2.html                    --> the template rendered for this module
    view2.js                      --> the application logic for this module
    view2_test.js              --> tests for view2 logic

  app.js                        --> main application module
  index.html                    --> app layout file (the main html template file of the app)
  index-async.html              --> just like index.html, but loads js files asynchronously

protractor.conf.js              --> config file for running e2e tests with Protractor
karma.conf.js                   --> config file for running unit tests with Karma

e2e/                            --> end-to-end tests
    scenarios.js

[petebacondarwin]

Another is:

app/                          --> all of the files to be used in production

  assets/                       --> all static asset files
    css/                          --> css files
    img/                          --> image files

  components/                   --> common app components (service, filters, directives)
    version
      version-directive.js
      version-directive_test.js
      version-filter.js
      version-filter_test.js
      version.js
      version_test.js

  view1/                        --> the view1 subsection
    view1.html                    --> the template rendered for this feature
    view1.js                      --> the application logic for this feature
    view1_test.js              --> tests for view1 logic

  view2/                        --> the view2 subsection
    view2.html                    --> the template rendered for this module
    view2.js                      --> the application logic for this module
    view2_test.js              --> tests for view2 logic

  app.js                        --> main application module
  app.css                       --> default stylesheet
  index.html                    --> app layout file (the main html template file of the app)
  index-async.html              --> just like index.html, but loads js files asynchronously

test
  protractor.conf.js              --> config file for running e2e tests with Protractor
  karma.conf.js                   --> config file for running unit tests with Karma
  e2e/                            --> end-to-end tests
    scenarios.js

[petebacondarwin]

The main difference appears to be in how to structure the components folder. (Along with slight differences in the test config and scenario file positions.

Any thoughts or comments? I know that @mbroadst had this to say:

The approach taken in the [first layout] recommend splitting up the directives, services, filters into separate folders. The "best practices" google document recommen[d]s splitting these files up only if they are unrelated. In fact, I don't think a single one of the examples given in that document approach the alternative to this PR. The services, directives and filters in this case are all related to the idea of a "version". See the section "A More Complex App Example" in the google doc to elaborate on my point.

In [the second layout], "version" is a number of elements logically separated as a single component. When would you just use an appVersion directive (you wouldn't, it depends on the "version" service)?. Why would it make sense for me to include a generic sounding "interpolate.js" script for a "version" filter? All in all, I think it makes a lot more sense design-wise this way, and I guess I just generally disagree that the other approach is either more intuitive, or more comprehensive.

[trevordmiller]

I agree with @mbroadst: PR #164 follows the proposed standards more closely than PR #210; the key difference is that code should be organized in folders by feature, not by type. PR #164 organizes by feature (like userlogin, adminlogin, subsection etc. as is shown in the official Google standards doc), whereas PR #210 organizes code by type (directives, filters, services etc.) - which is the old model.

The only suggestion I would give for PR #164 is to also include the CSS that belongs to each feature as is shown in the "A More Complex App Example" section of the doc (for example, in the userlogin/ component folder). This CSS can be linked to inside of the related directive / HTML partials or as part of a build process with CSS pre-processor partials and Grunt or Gulp: https://docs.google.com/document/d/1XXMvReO8-Awi1EZXAXS4PzDzdNvV6pGcuaF4Q9821Es/pub

[addisonedwardlee]

I have to agree that the structure of PR #164 makes a bit more sense, where you mimic the feature structure both inside and outside of the components folder. I can imagine as you build more and more directives, services, filters, etc. that the components folder would get quite difficult to manage without this setup.

@trevordmiller I know that the recommendation within the Google doc is to separate the CSS for each components, but since CSS doesn't have the idea of isolate scopes, I have a feeling that this might end up creating a system where one CSS style clobbers another. Imagine building a new feature that uses the CSS class item. You first need to check every other *.css to confirm it's not already being used. If you don't do this and simply add new styling for item within your feature's .css file (or overlook where it is being used), your shipped CSS file will end up having two item classes and your HTML will have some weird mix between the two of them. At least if all your CSS is in one file, a quick cmd+f before creating new stylings can save a lot of headache later.

[dancancro]

Why not just choose one of these, get behind it and stop supporting angular-seed altogether as a competing project?

And before you answer that question, please read this, especially the last point.

I made functional value comparisons between everything I knew about. For example, here's how angular-seed compares to Cleverstack:

angular-seed offers: 0% that Cleverstack doesn't (100% being the value of a perfect seed/generator)

• 0.3% Load Angular asynchronously
• 0.2% Dedicated/searchable user group
• 0.1% Coffeescript
• 0.1% CloudBees deployment automation
• 0.0% Approach to frontend class loading: script tags at the bottom
• 0.0% Approach to frontend class loading: angular.bootstrap()

CleverStack offers: 34% that angular-seed doesn't

• 5.0% Modular app files organization
• 1.7% Server-side integration & unit tests
• 1.7% Server-side performance tests
• 1.2% Code coverage reporting
• 0.8% Live Reload
• 0.8% One event-loop thread handles all requests
• 0.8% Approach to application functionality modules: Modularized Functionality
• 0.7% Approach to application functionality modules: Module manager
• 0.6% Command-line interface
• 0.5% factory
• 0.5% directive
• 0.5% Cross-Origin Resource Sharing (CORS)
• 0.5% Generator configures SQL db
• 0.5% Generator configures NoSQL db
• 0.5% model - client side
• 0.5% provider
• 0.4% Database migration/evolution system
• 0.4% filter
• 0.4% Source Maps
• 0.4% LESS
• 0.4% Authorization: Role-based
• 0.4% Authentication - Oauth
• 0.3% Share code between projects
• 0.3% Development build script
• 0.3% Production build script
• 0.3% config
• 0.3% controller - client side
• 0.3% service - client side
• 0.3% Object-document mapping
• 0.3% Object-relational mapping
• 0.3% Extra Angular things
• 0.3% Account Management: is password manager friendly
• 0.3% modal window
• 0.3% FEATURE (a.k.a. module, entity, crud-mock)
• 0.3% Twitter bootstrap styles
• 0.3% JavaScript obfuscation
• 0.3% Approach to frontend class loading: AMD with requirejs
• 0.3% Read-eval-print-loop (Repl)
• 0.3% test - client side
• 0.3% File Upload
• 0.3% Country list
• 0.3% Background task runner
• 0.3% Javascript performance thing
• 0.3% Serve URLs based on the route definitions
• 0.2% Development build script: html page processing
• 0.2% Browser detection
• 0.2% Documentation
• 0.2% Clustered HTTP sessions
• 0.2% Account Management
• 0.2% Digital fingerprint
• 0.2% Form generation
• 0.2% Account Management: Verify user registration by email
• 0.2% Shopping Cart
• 0.2% Amazon workflow
• 0.2% Multiple local Passport policies
• 0.2% Authentication - Google services
• 0.2% Reversible data deletion
• 0.2% Development build script: ...... change asset references to prevent caching
• 0.2% Production build script: generate build reports
• 0.2% Production build script: generate docs
• 0.2% Dedicated chatroom
• 0.2% Authentication - Token
• 0.2% Authentication - Cookie
• 0.1% Data tables
• 0.1% Development build script: reload build file upon change
• 0.1% Development build script: copy assets to build or dist or target folder
• 0.1% Development build script: Renames asset files to prevent browser caching
• 0.1% Development build script: LESS/SASS/etc files are linted, compiled
• 0.1% Development build script: basic JS analysis
• 0.1% Development build script: advanced JS analysis
• 0.1% Development build script: run unit tests
• 0.1% Development build script: run end to end tests
• 0.1% Development build script: coffee files compiled to JS
• 0.1% Production build script: concatenation
• 0.1% Production build script: minification
• 0.1% Production build script: safe pre-minification
• 0.1% Production build script: remove unused CSS
• 0.1% back end
• 0.1% controller - server side
• 0.1% model - server side
• 0.1% route - server side
• 0.1% service - server side
• 0.1% test - server side
• 0.1% Calendar
• 0.1% Alert messaging service
• 0.1% Currency list
• 0.1% Timezone list
• 0.1% Chat
• 0.1% E-Mail system
• 0.1% CSV processing
• 0.1% Survey
• 0.1% Configurable response caching
• 0.1% Serverside authenticated route restriction
• 0.1% Separate runtime configuration profiles
• 0.1% Serve status codes only as responses
• 0.1% Accept nested, JSON parameters
• 0.1% Add a mutex around requests
• 0.1% Add timer header to requests
• 0.1% Support for signed and encrypted cookies
• 0.1% Serve headers only
• 0.1% Production build script: uglification
• 0.1% Production build script: compress images
• 0.0% Approach to views: Dots in the model names
• 0.0% Approach to frontend controllers: Controllers contain no AJAX calls
• 0.0% Approach to ajax calls: uses $http

[trevordmiller]

@dancancro: I don't like all the options either...it is a little daunting at times! However, I feel that this project is extremely important to get right because it is Angular's official recommended start as shown on the official Angular website:

If anything, I think many of the other 3rd party setups should come to this repo and help to make it better instead of going off in their own directions, since this is the "official" one...at least on paper ;)

I just wish we as developers could gather around solutions to make a few really good things rather than so many varitions of the same things...quality over quantity. Sigh.

Thanks to @addyosmani for at least a little piece of sanity in all this: https://the-pastry-box-project.net/addy-osmani/2014-January-19

[dancancro]

@trevordmiller in my opinion, that link needs to be reconsidered and changed. "that's just the way it is" isn't exactly the sentiment of an innovator. I haven't checked, but I imagine angular-seed is the oldest. So you're right. The others should have improved angular-seed instead of going off on their own. I imagine that while the others were incubating as in-house tools, they weren't thinking much about releasing them to the world. So they didn't give much thought to the long run and ensuing choice paradox. But things are now as they are and a rational decision must accept and address reality.

I reckon this blog about open source government is worth reading to sum up the problem. TL;DR - too many Benevolent Dictators For Life spoils the, er, broth or something.

[petebacondarwin]

Please take a look at this PR, which I think combines the best of #210 and #164: #221

[addisonedwardlee]

@dancancro The goal of this thread is to determine which components angular-seed is missing and build those out. You've added a ton of great resources, which provide great inspiration for the things that should be included in this seed.

Looking at the list above, here are the things that I think we could add to make angular-seed the de-facto standard for new Angular projects

• App structure based on modules (In Progress - PR #221 )
• An example of a Factory
• An example of a Service ( the 'service' in angular-seed is a .value, which is overly simplified)
• An example of a Provider
• A better example of a Filter (based on comments from PR #221 )
• A Directive that uses an HTML template
• Adding content within the existing view1 and view2 Controllers

@trevordmiller @mbroadst @dancancro How do you guys feel about this list and are there other components you would like to see added? I think the goal should be to provide good examples without getting biased towards using specific tools (no db, build tools, etc.)

[dancancro]

@addisonedwardlee my opinion is to get behind a better project and discontinue angular-seed altogether. I don't have anything personal against angular-seed. It just doesn't do as much of my work as the others do. I have spelled out all of my reasons here. Please read it and find holes in my logic.

So I can't really give you an opinion about what features I think should be duplicated in angular-seed first. My comparison has a list of 230 weaknesses and 69 unknowns of angular-seed. I guess that's my list.

Why is it important for angular-seed to be "the standard"? I don't get that. The others have more functionality and have already solved way more problems and do more work for people. They are modular. If you don't want their backends you don't have to make them. If you don't want this or that feature, you just don't choose that option.

It would be a shame if time is spent duplicating work that's already been done in other projects, but I imagine there's a good chance that will end up happening. It's a pity.

[petebacondarwin]

OK, so I merged our refactoring.

Thanks to @mbroadst and @addisonedwardlee for their help (and patience) in getting this merged.

Please feel free to submit PRs with improvements, such as those suggested by @addisonedwardlee.

[ghost]

May someone please direct me to where-in-time I have to go back, to get the old layout? The old layout better fitted our needs as we usually develop features as an "app", which are later on bundled or not. Is commit commit 0edde11d781eb2834561db30c4b4a4778e27907c the last unrelated commit?

[petebacondarwin]

@fotofinder - yes that is the correct commit.